tensaku 0.0.1

data/lib/tensaku/endpoints.rb

@@ -0,0 +1,115 @@
+require "json"
+require "digest"
+
+module Tensaku
+  # The JSON endpoints the overlay talks to, plus the overlay script and the MCP endpoint. Everything
+  # except the script needs a loopback address, and everything the overlay calls needs the boot token.
+  class Endpoints
+    ASSET = File.expand_path("../../app/assets/tensaku.js", __dir__)
+
+    def self.asset_digest
+      Digest::SHA256.file(ASSET).hexdigest[0, 12]
+    rescue Errno::ENOENT
+      "missing"
+    end
+
+    # What the overlay last selected, for the MCP `current_selection` tool. One person, one browser.
+    def self.selection
+      @selection
+    end
+
+    def self.selection=(value)
+      @selection = value
+    end
+
+    def call(env)
+      request = Rack::Request.new(env)
+      path = request.path_info.delete_prefix(Tensaku.config.mount_path)
+
+      return script(request) if path == "/tensaku.js" && request.get?
+
+      if path == "/mcp"
+        Guard.check_local_client!(request)
+        return Mcp.new.call(request)
+      end
+
+      Guard.check_request!(request)
+      route(request, path)
+    rescue Forbidden => error
+      json({ error: error.message }, 403)
+    rescue StaleSource => error
+      json({ error: error.message, stale: true }, 409)
+    rescue Notes::NotFound => error
+      json({ error: error.message }, 404)
+    rescue Error, JSON::ParserError => error
+      json({ error: error.message }, 422)
+    end
+
+    private
+
+    def route(request, path)
+      params = request.get? ? request.GET : body(request)
+
+      case [ request.request_method, path ]
+      in [ "GET", "/source" ]
+        template, line, column = Source::Template.from_stamp(params["stamp"])
+        json(template.describe(line, column))
+      in [ "POST", "/text" ]
+        template, line, column = Source::Template.from_stamp(params["stamp"])
+        edits = Array(params["edits"]).map { it.to_h.symbolize_keys }
+        written(template.edit_text(line, column, edits), :template)
+      in [ "POST", "/attribute" ]
+        template, line, column = Source::Template.from_stamp(params["stamp"])
+        written(template.edit_attribute(line, column, params["name"].to_s, params.to_h.symbolize_keys), :template)
+      in [ "GET", "/translation" ]
+        json(key: params["key"], locales: Source::Locale.lookup_all(params["key"].to_s))
+      in [ "POST", "/translation" ]
+        result = Source::Locale.edit(params["locale"].to_s, params["key"].to_s, original: params["original"], text: params["text"])
+        written(result, :locale)
+      in [ "GET", "/markdown" ]
+        json(Source::Markdown.new(params["range"]).describe(tag: params["tag"]))
+      in [ "POST", "/markdown" ]
+        written(Source::Markdown.new(params["range"]).edit(original: params["original"], text: params["text"]), :markdown)
+      in [ "GET", "/notes" ]
+        Notes.prune!
+        json(notes: Notes.list(url: params["url"].presence, status: params["status"].presence), open: Notes.list(status: %w[open question]).size)
+      in [ "GET", "/notes.md" ]
+        notes = params["id"].present? ? [ Notes.find(params["id"]) ] : Notes.list(url: params["url"].presence, status: params["status"].presence || %w[open question])
+        [ 200, { "content-type" => "text/markdown; charset=utf-8" }, [ Notes.to_markdown(notes) ] ]
+      in [ "POST", "/notes" ]
+        json(Notes.create(params), 201)
+      in [ "PATCH", %r{\A/notes/([a-z0-9]+)\z} ]
+        id = path.split("/").last
+        json(Notes.update(id, status: params["status"], reply: params["reply"], comment: params["comment"]))
+      in [ "DELETE", %r{\A/notes/([a-z0-9]+)\z} ]
+        Notes.delete(path.split("/").last)
+        json({ deleted: true })
+      in [ "POST", "/selection" ]
+        self.class.selection = params.to_h.slice("url", "targets", "text").merge("at" => Time.now.utc.iso8601)
+        json({ ok: true })
+      else
+        json({ error: "Not found" }, 404)
+      end
+    end
+
+    def written(result, kind)
+      Caches.clear!(kind) if result[:changed]
+      json(result.merge(warning: Caches.fragment_cache_warning).compact)
+    end
+
+    def script(request)
+      raise Forbidden, "Tensaku only answers requests from this machine" unless Guard.loopback?(request)
+
+      [ 200, { "content-type" => "text/javascript; charset=utf-8", "cache-control" => "no-cache" }, [ File.read(ASSET) ] ]
+    end
+
+    def body(request)
+      raw = request.body&.read.to_s
+      raw.empty? ? {} : JSON.parse(raw)
+    end
+
+    def json(data, status = 200)
+      [ status, { "content-type" => "application/json; charset=utf-8", "cache-control" => "no-store" }, [ JSON.generate(data) ] ]
+    end
+  end
+end

data/lib/tensaku/file_write.rb

@@ -0,0 +1,33 @@
+module Tensaku
+  module FileWrite
+    module_function
+
+    # Writes through a temp file in the same directory and renames it over the original, keeping the
+    # file mode, so a crash can't leave half a file behind.
+    def atomic(path, content)
+      path = Pathname(path)
+      temp = path.dirname.join(".#{path.basename}.tensaku-#{SecureRandom.hex(4)}")
+      File.open(temp, File::WRONLY | File::CREAT | File::EXCL, path.stat.mode) do |file|
+        file.binmode
+        file.write(content)
+        file.fsync
+      end
+      File.rename(temp, path)
+    ensure
+      File.unlink(temp) if temp && File.exist?(temp)
+    end
+
+    # Replaces byte ranges in a string. Ranges must not overlap; they're applied back to front so the
+    # earlier offsets stay valid.
+    def splice(source, replacements)
+      result = source.b
+      replacements.sort_by { -it[:start] }.each_cons(2) do |later, earlier|
+        raise ArgumentError, "overlapping replacements" if earlier[:end] > later[:start]
+      end
+      replacements.sort_by { -it[:start] }.each do |replacement|
+        result[replacement[:start]...replacement[:end]] = replacement[:text].b
+      end
+      result.force_encoding(source.encoding)
+    end
+  end
+end

data/lib/tensaku/guard.rb

@@ -0,0 +1,77 @@
+require "ipaddr"
+
+module Tensaku
+  # Every endpoint goes through here: loopback addresses only, the boot token for anything that reads
+  # source or writes, and writes limited to the allow-list.
+  module Guard
+    LOOPBACK = [ IPAddr.new("127.0.0.0/8"), IPAddr.new("::1/128") ].freeze
+
+    module_function
+
+    def loopback?(request)
+      address = request.get_header("REMOTE_ADDR").to_s
+      LOOPBACK.any? { it.include?(IPAddr.new(address)) }
+    rescue IPAddr::InvalidAddressError
+      false
+    end
+
+    def check_request!(request)
+      raise Forbidden, "Tensaku only answers requests from this machine" unless loopback?(request)
+
+      token = request.get_header("HTTP_X_TENSAKU_TOKEN").to_s
+      raise Forbidden, "Missing or wrong Tensaku token. Reload the page." unless secure_compare(token, Tensaku.token)
+    end
+
+    # MCP clients can't read the page token, so the MCP endpoint relies on loopback plus a check that
+    # the request doesn't come from a web page (no foreign Origin, a local Host).
+    def check_local_client!(request)
+      raise Forbidden, "Tensaku only answers requests from this machine" unless loopback?(request)
+
+      origin = request.get_header("HTTP_ORIGIN")
+      raise Forbidden, "Cross-origin requests are refused" if origin && !local_url?(origin)
+
+      host = request.host.to_s
+      raise Forbidden, "Unexpected Host header" unless local_host?(host)
+    end
+
+    # Resolves a path from the page (relative to Rails.root) to a real file inside the allow-list.
+    def writable_file!(relative, extensions:)
+      raise Forbidden, "No file given" if relative.to_s.empty?
+
+      path = Tensaku.root.join(relative.to_s)
+      raise Forbidden, "#{relative} does not exist" unless path.file?
+
+      real = path.realpath
+      inside = writable_dirs.any? { real.to_s.start_with?("#{it}/") }
+      raise Forbidden, "#{relative} is outside Tensaku's writable paths (#{Tensaku.config.writable_paths.join(", ")})" unless inside
+
+      unless extensions.any? { real.basename.to_s.end_with?(it) }
+        raise Forbidden, "#{relative} is not a #{extensions.join(" or ")} file"
+      end
+
+      real
+    end
+
+    # The configured paths, plus Kiln's content directory when Kiln's content layer is loaded.
+    def writable_dirs
+      dirs = Tensaku.config.writable_paths.map { Tensaku.root.join(it) }
+      dirs << Pathname(Kiln::Content.root) if defined?(::Kiln::Content) && ::Kiln::Content.respond_to?(:root)
+      dirs.select(&:directory?).map(&:realpath)
+    end
+
+    def secure_compare(a, b)
+      a.bytesize == b.bytesize && OpenSSL.fixed_length_secure_compare(a, b)
+    end
+
+    def local_url?(url)
+      local_host?(URI.parse(url).host.to_s)
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def local_host?(host)
+      host = host.delete_prefix("[").delete_suffix("]")
+      host == "localhost" || host.end_with?(".localhost") || (IPAddr.new(host).loopback? rescue false)
+    end
+  end
+end

data/lib/tensaku/i18n.rb

@@ -0,0 +1,79 @@
+module Tensaku
+  # In development, translated strings carry an invisible marker with their locale and key, so the
+  # overlay knows which key produced a text or an attribute (the i18n_proofreading technique). The
+  # overlay strips the markers when the page loads.
+  #
+  # A marker is U+2063 (invisible separator), then "locale:key" as UTF-8 bytes written in base 4 with
+  # four zero-width characters, then U+2063 again. Nothing shows if the overlay never runs.
+  #
+  # Markers are only added while a controller handles an HTML request, never to `number.*`, `date.*`,
+  # `time.*` and similar keys, never to a value that came from a `default:` instead of the key, and
+  # never to pluralized lookups. A Ruby comparison against a translated string sees the marker, which
+  # is the known cost of this technique (development only).
+  module I18nMarkers
+    FENCE = "⁣"
+    DIGITS = [ "​", "‌", "‍", "⁠" ].freeze
+    PATTERN = /#{FENCE}[#{DIGITS.join}]+#{FENCE}/o
+    SKIP = /\A(?:number|date|time|datetime|support|i18n|helpers\.submit|errors\.format)(?:\.|\z)/
+
+    module_function
+
+    def active?
+      Thread.current[:tensaku_i18n_markers] == true
+    end
+
+    def with_markers
+      previous = Thread.current[:tensaku_i18n_markers]
+      Thread.current[:tensaku_i18n_markers] = true
+      yield
+    ensure
+      Thread.current[:tensaku_i18n_markers] = previous
+    end
+
+    def encode(locale, key)
+      digits = "#{locale}:#{key}".bytes.flat_map { |byte| 3.downto(0).map { DIGITS[(byte >> (it * 2)) & 3] } }
+      "#{FENCE}#{digits.join}#{FENCE}"
+    end
+
+    def decode(marker)
+      digits = marker.delete(FENCE).chars.map { DIGITS.index(it) }
+      digits.each_slice(4).map { |a, b, c, d| (a << 6) | (b << 4) | (c << 2) | d }.pack("C*").force_encoding(Encoding::UTF_8)
+    end
+
+    def strip(text)
+      text.include?(FENCE) ? text.gsub(PATTERN, "") : text
+    end
+
+    # Added to the app's I18n backend with `extend`, so it wraps whichever backend the app uses.
+    module Backend
+      def translate(locale, key, options = ::I18n::EMPTY_HASH)
+        result = super
+        return result unless I18nMarkers.active? && result.is_a?(String) && !key.nil?
+
+        full = ::I18n.normalize_keys(nil, key, options[:scope], options[:separator]).join(".")
+        return result if full.match?(SKIP)
+        return result unless lookup(locale, key, options[:scope], options).is_a?(String)
+
+        marked = result + I18nMarkers.encode(locale, full)
+        result.html_safe? ? marked.html_safe : marked
+      end
+    end
+
+    # Wraps controller actions for HTML requests.
+    module Controller
+      extend ActiveSupport::Concern
+
+      included do
+        prepend_around_action :tensaku_i18n_markers
+      end
+
+      private
+
+      def tensaku_i18n_markers(&)
+        return yield unless request.format&.html?
+
+        I18nMarkers.with_markers(&)
+      end
+    end
+  end
+end

data/lib/tensaku/mcp.rb

@@ -0,0 +1,135 @@
+require "json"
+
+module Tensaku
+  # A small MCP server (Streamable HTTP transport, JSON responses, no sessions) on the dev server, so
+  # an agent can read and resolve notes. Configure it in .mcp.json as an http server at
+  # http://localhost:3000/__tensaku/mcp.
+  class Mcp
+    PROTOCOL_VERSIONS = %w[2025-11-25 2025-06-18 2025-03-26 2024-11-05].freeze
+    MAX_WATCH = 300
+
+    TOOLS = [
+      {
+        name: "list_notes",
+        description: "List Tensaku notes left on pages of this Rails app. Each note has a comment and targets with the exact file and line range that rendered the element. Defaults to notes that need work (open and question).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            status: { type: "string", enum: %w[open question resolved active all], description: "active (default) means open or question." },
+            url: { type: "string", description: "Only notes left on this path, for example /about." }
+          }
+        }
+      },
+      {
+        name: "get_note",
+        description: "Get one Tensaku note by id.",
+        inputSchema: { type: "object", properties: { id: { type: "string" } }, required: [ "id" ] }
+      },
+      {
+        name: "resolve_note",
+        description: "Mark a note resolved after making the change. The reply is shown on the page next to a green pin, so say briefly what changed and where (for example: changed the heading in app/views/pages/_hero.html.erb:4).",
+        inputSchema: { type: "object", properties: { id: { type: "string" }, reply: { type: "string" } }, required: %w[id reply] }
+      },
+      {
+        name: "ask_question",
+        description: "Ask the person who wrote a note for clarification instead of guessing. The question shows on the page; the note's status becomes question until they answer by editing the note.",
+        inputSchema: { type: "object", properties: { id: { type: "string" }, question: { type: "string" } }, required: %w[id question] }
+      },
+      {
+        name: "watch_notes",
+        description: "Wait for new or changed open notes, so you can work through notes as they are added. Returns as soon as there are any, or empty after the timeout. Pass the checked_at value of the previous call as since so nothing is missed.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            since: { type: "string", description: "ISO 8601 time. Defaults to now." },
+            timeout_seconds: { type: "integer", minimum: 1, maximum: MAX_WATCH, description: "Defaults to 60." }
+          }
+        }
+      },
+      {
+        name: "current_selection",
+        description: "What the person last selected in the Tensaku overlay (elements with file and line), for questions like 'what is this?'.",
+        inputSchema: { type: "object", properties: {} }
+      }
+    ].freeze
+
+    def call(request)
+      return [ 405, { "allow" => "POST" }, [ "" ] ] unless request.post?
+
+      message = JSON.parse(request.body.read.to_s)
+      responses = Array.wrap(message).filter_map { respond(it) }
+      return [ 202, {}, [ "" ] ] if responses.empty?
+
+      payload = message.is_a?(Array) ? responses : responses.first
+      [ 200, { "content-type" => "application/json" }, [ JSON.generate(payload) ] ]
+    rescue JSON::ParserError
+      [ 400, { "content-type" => "application/json" }, [ JSON.generate(error_payload(nil, -32700, "Parse error")) ] ]
+    end
+
+    private
+
+    def respond(message)
+      id = message["id"]
+      return nil if id.nil? # a notification
+
+      result = case message["method"]
+      when "initialize" then initialize_result(message.dig("params", "protocolVersion"))
+      when "ping" then {}
+      when "tools/list" then { tools: TOOLS }
+      when "tools/call" then call_tool(message.dig("params", "name"), message.dig("params", "arguments") || {})
+      else return error_payload(id, -32601, "Method not found: #{message["method"]}")
+      end
+      { jsonrpc: "2.0", id:, result: }
+    end
+
+    def initialize_result(requested)
+      {
+        protocolVersion: PROTOCOL_VERSIONS.include?(requested) ? requested : PROTOCOL_VERSIONS.first,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: "tensaku", version: Tensaku::VERSION },
+        instructions: "Tensaku notes are comments a person left on pages of this Rails app, each with the file and line that rendered the element. Act on open notes, then resolve each with a short reply, or ask a question when a note is unclear."
+      }
+    end
+
+    def call_tool(name, arguments)
+      case name
+      when "list_notes"
+        status = arguments["status"].presence || "active"
+        statuses = { "active" => %w[open question], "all" => nil }.fetch(status, status)
+        notes = Notes.list(url: arguments["url"].presence, status: statuses)
+        tool_result(Notes.to_markdown(notes), notes:, checked_at: Time.now.utc.iso8601)
+      when "get_note"
+        note = Notes.find(arguments["id"])
+        tool_result(Notes.note_markdown(note), note:)
+      when "resolve_note"
+        note = Notes.update(arguments["id"], status: "resolved", reply: arguments["reply"])
+        tool_result("Resolved note #{note["id"]}.", note:)
+      when "ask_question"
+        note = Notes.update(arguments["id"], status: "question", reply: arguments["question"])
+        tool_result("Asked on note #{note["id"]}. It shows on the page until the person answers.", note:)
+      when "watch_notes"
+        since = arguments["since"].present? ? Time.iso8601(arguments["since"]) : Time.now.utc
+        timeout = arguments["timeout_seconds"].to_i.clamp(1, MAX_WATCH)
+        timeout = 60 if arguments["timeout_seconds"].nil?
+        notes = Notes.watch(since:, timeout:)
+        text = notes.empty? ? "No new notes in #{timeout}s. Call watch_notes again to keep waiting." : Notes.to_markdown(notes)
+        tool_result(text, notes:, checked_at: Time.now.utc.iso8601)
+      when "current_selection"
+        selection = Endpoints.selection
+        tool_result(selection ? JSON.pretty_generate(selection) : "Nothing selected in the Tensaku overlay yet.", selection:)
+      else
+        tool_result("Unknown tool #{name}", error: true)
+      end
+    rescue Notes::NotFound, Error, ArgumentError => error
+      tool_result(error.message, error: true)
+    end
+
+    def tool_result(text, error: false, **structured)
+      { content: [ { type: "text", text: } ], structuredContent: structured.presence, isError: error }.compact
+    end
+
+    def error_payload(id, code, message)
+      { jsonrpc: "2.0", id:, error: { code:, message: } }
+    end
+  end
+end

data/lib/tensaku/middleware.rb

@@ -0,0 +1,62 @@
+module Tensaku
+  # Development only. Serves the overlay and the endpoints under Tensaku.config.mount_path, and adds
+  # the overlay to HTML pages: a meta tag with the request method and the boot token in <head>, and the
+  # script before </body>.
+  class Middleware
+    HTML = %r{\Atext/html}
+    STRIP_TYPES = %r{\A(?:text/|application/(?:json|xml|javascript|ld\+json))}
+    SCRIPT_OR_STYLE = %r{(<(script|style)\b[^>]*>)(.*?)(</\2>)}im
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      return Endpoints.new.call(env) if env["PATH_INFO"].to_s.start_with?("#{Tensaku.config.mount_path}/")
+
+      status, headers, body = @app.call(env)
+      type = headers["content-type"].to_s
+      return [ status, headers, body ] if status == 204 || status == 304 || headers["content-disposition"].to_s.start_with?("attachment")
+
+      if type.match?(HTML) && !headers["content-encoding"]
+        rewrite(status, headers, body) { inject(it, env) }
+      elsif type.match?(STRIP_TYPES) && !headers["content-encoding"] && !type.include?("event-stream")
+        rewrite(status, headers, body) { I18nMarkers.strip(it) }
+      else
+        [ status, headers, body ]
+      end
+    end
+
+    private
+
+    def rewrite(status, headers, body)
+      html = +""
+      body.each { html << it }
+      body.close if body.respond_to?(:close)
+      html = yield(html.force_encoding(Encoding::UTF_8))
+      headers = headers.dup
+      headers.delete("content-length")
+      headers.delete("etag")
+      [ status, headers, [ html ] ]
+    end
+
+    def inject(html, env)
+      # Markers inside scripts and styles would end up in code; the overlay can't reach those.
+      html = html.gsub(SCRIPT_OR_STYLE) { "#{$1}#{I18nMarkers.strip($3)}#{$4}" } if html.include?(I18nMarkers::FENCE)
+      return html if html.include?("data-tensaku-request=")
+
+      meta = %(<meta name="tensaku" data-tensaku-request="#{ERB::Util.h(env["REQUEST_METHOD"])}" data-tensaku-token="#{Tensaku.token}" data-tensaku-root="#{ERB::Util.h(Tensaku.config.mount_path)}" data-tensaku-shortcut="#{ERB::Util.h(Tensaku.config.shortcut)}">)
+      script = %(<script src="#{Tensaku.config.mount_path}/tensaku.js?v=#{Endpoints.asset_digest}" data-turbo-eval="false" data-tensaku-ui defer></script>)
+
+      html = insert_before(html, "</head>", meta) || "#{meta}#{html}"
+      insert_before(html, "</body>", script) || "#{html}#{script}"
+    end
+
+    def insert_before(html, tag, snippet)
+      index = html.rindex(/#{Regexp.escape(tag)}/i)
+      return nil unless index
+
+      html.dup.insert(index, snippet)
+    end
+  end
+end