tensaku 0.0.1

data/lib/tensaku/source/template.rb

@@ -0,0 +1,252 @@
+require "herb"
+require "tensaku/source/html_text"
+
+module Tensaku
+  module Source
+    # An ERB template, read through Herb, addressed by the element stamps Herb's
+    # SourceAttributionVisitor writes (`data-herb-source="path:line:col"`, 1-based).
+    #
+    # Pieces are the element's children as they are in the file: static text (editable), Ruby output
+    # and control flow (locked), child elements (locked, edited on their own) and comments (hidden).
+    class Template
+      PARSE_OPTIONS = { track_locations: true, action_view_helpers: true }.freeze
+      EXTENSIONS = %w[.erb].freeze
+
+      # Attributes people read. `value` only counts on buttons.
+      ATTRIBUTES = %w[alt title placeholder aria-label value].freeze
+      BUTTON_INPUTS = %w[submit button reset].freeze
+
+      OUTPUT_TAGS = %w[<%= <%==].freeze
+
+      attr_reader :relative_path, :source
+
+      def self.parse_stamp(stamp)
+        match = stamp.to_s.match(/\A(?<path>.+):(?<line>\d+):(?<column>\d+)\z/)
+        raise Error, "Not a source stamp: #{stamp.inspect}" unless match
+
+        [ match[:path], match[:line].to_i, match[:column].to_i ]
+      end
+
+      def self.from_stamp(stamp)
+        path, line, column = parse_stamp(stamp)
+        [ new(path), line, column ]
+      end
+
+      def initialize(relative_path)
+        @relative_path = relative_path
+        @path = Guard.writable_file!(relative_path, extensions: EXTENSIONS)
+        @source = File.read(@path, mode: "rb").force_encoding(Encoding::UTF_8)
+        @line_starts = [ 0 ]
+        @source.b.each_line { @line_starts << @line_starts.last + it.bytesize }
+      end
+
+      # What the overlay needs to edit or annotate the element written at line:column.
+      def describe(line, column)
+        element = element_at!(line, column)
+        helper = !element.open_tag.is_a?(Herb::AST::HTMLOpenTagNode)
+        pieces = helper ? [] : pieces_of(element)
+        {
+          file: relative_path,
+          stamp: "#{relative_path}:#{line}:#{column}",
+          range: range_label(element.location),
+          tag: tag_label(element),
+          helper:,
+          editable: !helper && pieces.any? { it[:kind] == "text" && !it[:text].strip.empty? },
+          pieces:,
+          attributes: helper ? [] : attributes_of(element)
+        }
+      end
+
+      # The file range of the element, for notes: "line:col-line:col".
+      def element_range(line, column)
+        element = element_at!(line, column)
+        { range: range_label(element.location), tag: tag_label(element) }
+      end
+
+      # edits: [{ start:, end:, original:, text: }], byte ranges of text pieces with the source they had
+      # when the page loaded, and the new text as shown in the browser.
+      def edit_text(line, column, edits)
+        element = element_at!(line, column)
+        pieces = pieces_of(element).select { it[:kind] == "text" }
+
+        replacements = edits.map do |edit|
+          piece = pieces.find { it[:start] == edit[:start].to_i && it[:end] == edit[:end].to_i }
+          stale! unless piece && piece[:raw] == edit[:original]
+
+          text = HtmlText.new(piece[:raw], trim_start: piece[:trim_start], trim_end: piece[:trim_end])
+          { start: piece[:start], end: piece[:end], text: text.rewrite(clean(edit[:text]), escape: HtmlText.method(:escape_text)) }
+        end
+
+        write(replacements)
+      end
+
+      def edit_attribute(line, column, name, edit)
+        element = element_at!(line, column)
+        attribute = attributes_of(element).find { it[:name] == name }
+        stale! unless attribute
+        raise Error, "#{name} has an unquoted value. Quote it in the template first." unless attribute[:quote]
+
+        piece = attribute[:pieces].find { it[:kind] == "text" && it[:start] == edit[:start].to_i && it[:end] == edit[:end].to_i }
+        stale! unless piece && piece[:raw] == edit[:original]
+
+        rewritten = HtmlText.new(piece[:raw], collapse: false).rewrite(clean(edit[:text]), escape: HtmlText.attribute_escaper(attribute[:quote]))
+        write([ { start: piece[:start], end: piece[:end], text: rewritten } ])
+      end
+
+      private
+
+      def element_at!(line, column)
+        finder = ElementFinder.new(line, column - 1)
+        Herb.parse(source, **PARSE_OPTIONS).value.accept(finder)
+        finder.found or stale!("No element starts at #{relative_path}:#{line}:#{column} any more. Reload the page.")
+      end
+
+      def stale!(message = nil)
+        raise StaleSource, message || "#{relative_path} changed since the page was rendered. Reload the page and try again."
+      end
+
+      def write(replacements)
+        replacements = replacements.reject { source.byteslice(it[:start]...it[:end]) == it[:text] }
+        return { changed: false } if replacements.empty?
+
+        FileWrite.atomic(@path, FileWrite.splice(source, replacements))
+        { changed: true, file: relative_path }
+      end
+
+      # Browsers hand back non-breaking spaces for typed runs of spaces in editable text.
+      def clean(text)
+        text.to_s.tr(" ", " ").delete("\r")
+      end
+
+      def pieces_of(element)
+        body = element.body
+        body.each_with_index.map do |node, index|
+          case node
+          when Herb::AST::HTMLTextNode
+            start, finish = byte_range(node.location)
+            raw = source.byteslice(start...finish)
+            trim_start = index.zero?
+            trim_end = index == body.size - 1
+            text = HtmlText.new(raw, trim_start:, trim_end:).text
+            { kind: "text", start:, end: finish, raw:, text:, trim_start:, trim_end: }
+          when Herb::AST::ERBContentNode
+            opening = node.tag_opening.value
+            if OUTPUT_TAGS.include?(opening)
+              { kind: "ruby", code: node.content.value.strip }
+            else
+              { kind: "hidden" }
+            end
+          when Herb::AST::HTMLElementNode
+            { kind: "element", tag: tag_label(node), label: label_of(node), stamp: stamp_of(node) }
+          when Herb::AST::HTMLCommentNode, Herb::AST::ERBYieldNode
+            { kind: "hidden" }
+          else
+            { kind: "ruby", code: summary_of(node) }
+          end
+        end
+      end
+
+      def attributes_of(element)
+        tag = element.tag_name&.value.to_s.downcase
+        nodes = element.open_tag.children.grep(Herb::AST::HTMLAttributeNode)
+        type = static_attribute(nodes, "type").to_s.downcase
+
+        nodes.filter_map do |node|
+          name = attribute_name(node)
+          next unless ATTRIBUTES.include?(name)
+          next if name == "value" && !(tag == "button" || (tag == "input" && BUTTON_INPUTS.include?(type)))
+          next unless node.value
+
+          quote = node.value.quoted ? node.value.open_quote&.value : nil
+          pieces = node.value.children.map do |child|
+            case child
+            when Herb::AST::LiteralNode
+              start, finish = byte_range(child.location)
+              raw = source.byteslice(start...finish)
+              { kind: "text", start:, end: finish, raw:, text: HtmlText.new(raw, collapse: false).text }
+            when Herb::AST::ERBContentNode
+              { kind: "ruby", code: child.content.value.strip }
+            else
+              { kind: "ruby", code: summary_of(child) }
+            end
+          end
+          { name:, quote:, pieces: }
+        end
+      end
+
+      def attribute_name(node)
+        node.name&.children&.filter_map { it.content if it.is_a?(Herb::AST::LiteralNode) }&.join&.downcase
+      end
+
+      def static_attribute(nodes, name)
+        node = nodes.find { attribute_name(it) == name }
+        node&.value&.children&.grep(Herb::AST::LiteralNode)&.map(&:content)&.join
+      end
+
+      def tag_label(element)
+        tag = element.tag_name&.value.to_s.downcase
+        return tag unless element.open_tag.respond_to?(:children)
+
+        nodes = element.open_tag.children.grep(Herb::AST::HTMLAttributeNode)
+        id = static_attribute(nodes, "id")
+        classes = static_attribute(nodes, "class").to_s.split.first
+        return "#{tag}##{id}" if id.present?
+        return "#{tag}.#{classes}" if classes.present?
+
+        tag
+      end
+
+      def label_of(element)
+        text = element.body.filter_map do |child|
+          case child
+          when Herb::AST::HTMLTextNode then child.content
+          when Herb::AST::HTMLElementNode then label_of(child)
+          when Herb::AST::ERBContentNode then "…" if OUTPUT_TAGS.include?(child.tag_opening.value)
+          end
+        end.join.squish
+        text.length > 40 ? "#{text[0, 39]}…" : text
+      end
+
+      def summary_of(node)
+        opening = node.respond_to?(:content) && node.content.respond_to?(:value) ? node.content.value : nil
+        (opening || node.class.name.demodulize).strip.lines.first.to_s.strip
+      end
+
+      def stamp_of(node)
+        start = node.open_tag.location.start
+        "#{relative_path}:#{start.line}:#{start.column + 1}"
+      end
+
+      # Herb positions are 1-based lines and 0-based character columns.
+      def byte_offset(position)
+        line_start = @line_starts.fetch(position.line - 1)
+        line = source.b[line_start...@line_starts.fetch(position.line, source.bytesize)].force_encoding(Encoding::UTF_8)
+        line_start + line[0, position.column].bytesize
+      end
+
+      def byte_range(location)
+        [ byte_offset(location.start), byte_offset(location.end) ]
+      end
+
+      def range_label(location)
+        "#{location.start.line}:#{location.start.column + 1}-#{location.end.line}:#{location.end.column + 1}"
+      end
+
+      class ElementFinder < Herb::Visitor
+        attr_reader :found
+
+        def initialize(line, column)
+          super()
+          @line = line
+          @column = column
+        end
+
+        def visit_html_element_node(node)
+          start = node.open_tag&.location&.start
+          @found ||= node if start && start.line == @line && start.column == @column
+          super unless @found
+        end
+      end
+    end
+  end
+end

data/lib/tensaku/version.rb

@@ -0,0 +1,3 @@
+module Tensaku
+  VERSION = "0.0.1"
+end

data/lib/tensaku.rb

@@ -0,0 +1,91 @@
+require "securerandom"
+require "tensaku/version"
+
+# Tensaku edits text on a running Rails page and writes it back to the source, and keeps notes for
+# coding agents. It does nothing outside development (see Tensaku.enabled?).
+module Tensaku
+  # Loaded on first use, so an app that lists Tensaku in the wrong Gemfile group loads none of it
+  # (nor Herb) outside development.
+  autoload :Guard, "tensaku/guard"
+  autoload :FileWrite, "tensaku/file_write"
+  autoload :Middleware, "tensaku/middleware"
+  autoload :Endpoints, "tensaku/endpoints"
+  autoload :Notes, "tensaku/notes"
+  autoload :Mcp, "tensaku/mcp"
+  autoload :Caches, "tensaku/caches"
+  autoload :I18nMarkers, "tensaku/i18n"
+
+  module Source
+    autoload :HtmlText, "tensaku/source/html_text"
+    autoload :Template, "tensaku/source/template"
+    autoload :Locale, "tensaku/source/locale"
+    autoload :Markdown, "tensaku/source/markdown"
+  end
+
+  class Error < StandardError; end
+
+  # A write that would change the wrong bytes: the file changed since the page rendered, or the target
+  # moved. Nothing is merged or guessed.
+  class StaleSource < Error; end
+
+  # A request the guard refuses: not loopback, wrong token, or a path outside the allow-list.
+  class Forbidden < Error; end
+
+  class Config
+    # Directories, relative to Rails.root, that Tensaku may write to.
+    attr_reader :writable_paths
+
+    # Where note files live, relative to Rails.root.
+    attr_accessor :notes_path
+
+    # Resolved notes older than this are deleted.
+    attr_accessor :prune_after
+
+    # Keyboard shortcut that toggles the overlay, as modifier keys and a KeyboardEvent#code.
+    attr_accessor :shortcut
+
+    # Where the middleware serves the overlay and the endpoints.
+    attr_accessor :mount_path
+
+    def initialize
+      @writable_paths = %w[app/views app/components config/locales]
+      @notes_path = "tmp/tensaku/notes"
+      @prune_after = 3 * 24 * 60 * 60
+      @shortcut = "alt+shift+KeyT"
+      @mount_path = "/__tensaku"
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # Lets another gem allow writes to its own source directory, for example Kiln's content/.
+    def register_writable_path(path)
+      config.writable_paths << path.to_s unless config.writable_paths.include?(path.to_s)
+    end
+
+    def enabled?
+      defined?(Rails) && Rails.env.development?
+    end
+
+    # A per-boot secret embedded in the page. Write requests must echo it back.
+    def token
+      @token ||= SecureRandom.hex(16)
+    end
+
+    # The app root that relative source paths resolve against. Tests point it at a scratch copy.
+    attr_writer :root
+
+    def root
+      Pathname(@root || Rails.root)
+    end
+  end
+end
+
+require "tensaku/railtie" if defined?(Rails::Railtie)

data/skills/tensaku/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: tensaku
+description: Work through Tensaku notes, the comments a person left on pages of this Rails app in development, each pointing at the exact file and line that rendered the element. Use when the user mentions Tensaku, notes on the page, "my notes", or asks you to go through what they marked up in the browser.
+---
+
+# Tensaku notes
+
+Tensaku is a development-only overlay for this Rails app. The person clicks an element (or drags over an
+area) on a running page and writes what should change. Each note records the page URL, the comment, and
+one or more targets with the source position Herb stamped on the element.
+
+## Finding notes
+
+Use whichever is available, in this order:
+
+1. **MCP**: the `tensaku` server (`/__tensaku/mcp` on the dev server). Tools: `list_notes`, `get_note`,
+   `resolve_note`, `ask_question`, `watch_notes`, `current_selection`. The dev server must be running.
+2. **Files**: `tmp/tensaku/notes/*.json`, one note per file. Read them directly when the server isn't
+   running. Edit `status` and `reply` in the file to resolve one.
+
+A note looks like this:
+
+```json
+{
+  "id": "a7f3",
+  "url": "/about",
+  "comment": "tighten this, and the heading is wrong",
+  "targets": [
+    { "kind": "element", "file": "app/views/pages/_hero.html.erb", "range": "4:3-4:40", "tag": "h1", "text": "About me",
+      "context": { "partials": ["app/views/pages/_hero.html.erb", "app/views/pages/about.html.erb"], "controller": "hero" } },
+    { "kind": "translation", "key": "pages.about.title", "locale": "en", "file": "config/locales/en.yml", "range": "12" }
+  ],
+  "rect": { "x": 120, "y": 340, "width": 600, "height": 180 },
+  "status": "open",
+  "reply": null
+}
+```
+
+- `range` is `line:column-line:column` in `file` (1-based). For translations it's the line of the key.
+- `kind` is `element`, `text` (the person selected that text), `translation` (the text came from that
+  I18n key) or `markdown` (a Markdown source block).
+- `rect` is set for area notes: the person dragged over a region, and `targets` lists the elements in it.
+- An element rendered in a loop or a repeated partial has one source position for every copy.
+- Text from Ruby (`<%= @post.title %>`) points at the ERB expression; the data itself lives elsewhere.
+
+## Working through notes
+
+1. List the open notes (`list_notes`, or read the files with `"status": "open"`).
+2. For each note, open the target file at the range, read the comment, and make the change. Look at
+   `context.partials` when the fix belongs in a parent template, and at the translation target when the
+   text comes from a locale file (change every locale that needs it).
+3. If the comment is ambiguous, don't guess: call `ask_question` with a short, specific question. The
+   question shows on the page and the note waits for an answer.
+4. When done, call `resolve_note` with a one-line reply that says what changed and where, for example
+   `Shortened the intro in app/views/pages/_hero.html.erb:6`. The pin on the page turns green so the
+   person can check it.
+
+To keep going while the person adds notes, call `watch_notes` in a loop, passing the previous
+`checked_at` as `since`.
+
+You can take a screenshot of `url` with a browser tool if the layout matters; notes don't include one.

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: tensaku
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- David Afonso
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: herb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.11.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.11.2
+- !ruby/object:Gem::Dependency
+  name: reactionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.1
+description: Tensaku lets you click text on a Rails page in development and write
+  the change back to the ERB template, the locale YAML or the Markdown source, or
+  leave notes on elements and areas that a coding agent reads with the exact file
+  and line. Built on Herb through ReActionView. Development only.
+email:
+- dav@davafons.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/assets/tensaku.js
+- lib/generators/tensaku/install_generator.rb
+- lib/tensaku.rb
+- lib/tensaku/caches.rb
+- lib/tensaku/endpoints.rb
+- lib/tensaku/file_write.rb
+- lib/tensaku/guard.rb
+- lib/tensaku/i18n.rb
+- lib/tensaku/mcp.rb
+- lib/tensaku/middleware.rb
+- lib/tensaku/notes.rb
+- lib/tensaku/railtie.rb
+- lib/tensaku/source/html_text.rb
+- lib/tensaku/source/locale.rb
+- lib/tensaku/source/markdown.rb
+- lib/tensaku/source/template.rb
+- lib/tensaku/version.rb
+- skills/tensaku/SKILL.md
+homepage: https://github.com/davafons/tensaku
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/davafons/tensaku
+  source_code_uri: https://github.com/davafons/tensaku
+  changelog_uri: https://github.com/davafons/tensaku/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Edit text and leave notes for your coding agent on a running Rails page,
+  in development.
+test_files: []