esp-modkit 0.1.0

data/lib/esp/http_server.rb

@@ -0,0 +1,232 @@
+require 'json'
+require 'webrick'
+
+# WEBrick's mount_proc registers a ProcHandler whose do_GET / do_POST /
+# do_HEAD / do_PUT all route through the supplied proc — but do_OPTIONS is
+# inherited from AbstractServlet, which short-circuits with an `Allow:`
+# response and **never calls the proc**. That means our dispatch's CORS
+# headers don't get attached to the preflight, and any cross-origin POST
+# with a JSON body (everything from the ESPresso webview) is blocked by
+# the browser. Patch ProcHandler so OPTIONS flows through the proc like
+# every other method.
+WEBrick::HTTPServlet::ProcHandler.class_eval do
+  def do_OPTIONS(req, res)
+    @proc.call(req, res)
+  end
+end
+
+module Esp
+  # Localhost HTTP API mirroring the CLI surface. A thin WEBrick shell over
+  # Esp::Operations — same operations as `bin/esp` and `esp mcp serve`, same
+  # payload shapes, different transport. Intended as the backing store for
+  # the GUI. WEBrick is thread-per-request, so the long-lived /agent stream
+  # doesn't block other routes.
+  #
+  # Routes:
+  #   POST /agent             — body: { prompt, provider?, model? } → text/event-stream
+  #   GET  /up                — { status, version }  (liveness)
+  #   GET  /version           — { version }
+  #   GET  /commands          — full Esp::Introspection.command_tree
+  #   GET  /providers         — { providers:[{id,default_model,configured}], default }
+  #   GET  /active-project    — { root: String|null }
+  #   POST /open-project      — body: { root } → { root }  (sets active project)
+  #   GET  /projects/recent   — { projects: [{root,name,opened_at}, ...] }
+  #   POST /projects/new      — body: { project, mod, format?, author? } → { root, mod, source }
+  #   GET  /preferences       — { mods_home, ... } (merged over defaults)
+  #   POST /preferences       — body: { mods_home?, ... } → resolved prefs
+  #   POST /build             — body: { mod, locale? }
+  #   POST /build-all         — body: { locale? }
+  #   POST /unpack            — body: { plugin, name? }
+  #   POST /install           — body: { mod }
+  #   POST /lint              — body: { mod }
+  #   POST /i18n/check        — body: { mod }
+  #   POST /scaffold          — body: { mod, format?, author?, description?, force? }
+  #   POST /extract-scripts   — body: { mod }
+  #   POST /records/read      — body: { mod }
+  #   POST /records/write     — body: { mod, record }
+  #   POST /dialogue/write    — body: { mod, spec }
+  #   GET  /plugins           — query: config?
+  #   GET  /refs/find         — query: q, type, like, limit, show
+  #   POST /refs/resolve      — body: { ids: [String] } → { types: {id => type} }
+  #   GET  /ollama/models     — { models: [String] } from Ollama's /api/tags
+  #   GET  /diff              — query: scope?, root?  (working-tree changes + diffs)
+  #   POST /approve           — body: { paths, root? }  (git add)
+  #   POST /reject            — body: { paths, root? }  (restore/delete — destructive)
+  #
+  # CORS is wide open (Access-Control-Allow-Origin: *) — dev-only tool.
+  class HttpServer
+    DEFAULT_PORT = 4567
+
+    # [verb, path, Operations method]. Every route is a thin pass of the
+    # parsed input (query for GET, JSON body for POST) to one operation, so
+    # adding an endpoint is a one-line row here.
+    ROUTES = [
+      [:get,  '/up',              :health],
+      [:get,  '/version',         :version],
+      [:get,  '/commands',        :commands],
+      [:get,  '/providers',       :providers],
+      [:get,  '/active-project',  :active_project],
+      [:post, '/open-project',    :open_project],
+      [:get,  '/projects/recent', :projects_recent],
+      [:post, '/projects/new',    :projects_new],
+      [:get,  '/preferences',     :preferences],
+      [:post, '/preferences',     :preferences_update],
+      [:get,  '/plugins',         :plugins_list],
+      [:get,  '/refs/find',       :refs_find],
+      [:post, '/refs/resolve',    :refs_resolve],
+      [:get,  '/ollama/models',   :ollama_models],
+      [:get,  '/diff',            :diff],
+      [:post, '/approve',         :approve],
+      [:post, '/reject',          :reject],
+      [:post, '/build',           :build],
+      [:post, '/build-all',       :build_all],
+      [:post, '/unpack',          :unpack],
+      [:post, '/install',         :install],
+      [:post, '/lint',            :lint],
+      [:post, '/i18n/check',      :i18n_check],
+      [:post, '/scaffold',        :scaffold],
+      [:post, '/extract-scripts', :extract_scripts],
+      [:post, '/records/read',    :records_read],
+      [:post, '/records/write',   :record_write],
+      [:post, '/dialogue/write',  :dialogue_write]
+    ].freeze
+
+    def initialize(port: DEFAULT_PORT, logger: nil, agent: nil)
+      @port = port
+      # An injected agent (tests) is used as-is; otherwise each /agent request
+      # builds one for its chosen provider/model.
+      @agent = agent
+      @server = WEBrick::HTTPServer.new(
+        Port: port,
+        Logger: logger || WEBrick::Log.new($stdout, WEBrick::Log::WARN),
+        AccessLog: []
+      )
+      register_routes
+    end
+
+    def start
+      trap('INT')  { stop }
+      trap('TERM') { stop }
+      @server.start
+    end
+
+    def stop
+      @server.shutdown
+    end
+
+    private
+
+    def register_routes
+      ROUTES.each do |verb, path, op|
+        mount(verb.to_s.upcase, path) { |input| Esp::Operations.dispatch(op, input) }
+      end
+      @server.mount_proc('/agent') { |req, res| stream_agent(req, res) }
+    end
+
+    # The agent loop streamed as Server-Sent Events. Runs in a WEBrick
+    # request thread; the agent's events are piped out as they arrive so the
+    # GUI renders the trace live. The API key lives in the backend's env,
+    # never the webview.
+    def stream_agent(req, res)
+      cors_headers(res)
+      return cors_preflight(res) if req.request_method == 'OPTIONS'
+      unless req.request_method == 'POST'
+        return send_error(res, 405, 'method not allowed (expected POST)', error_code: 'method_not_allowed')
+      end
+
+      body = parse_input(req, 'POST')
+      # Build the chosen provider before opening the stream, so a bad
+      # provider/model is a clean 400 rather than a half-open event stream.
+      agent = @agent || build_agent(body)
+      res.status = 200
+      res['Content-Type'] = 'text/event-stream'
+      res['Cache-Control'] = 'no-cache'
+      res.chunked = true
+      reader, writer = IO.pipe
+      Thread.new { pump_agent(agent, body['prompt'].to_s, writer) }
+      res.body = reader
+    rescue *Esp::Operations.caller_errors => e
+      send_error(res, 400, e.message, error_code: Esp::Operations.error_code(e))
+    end
+
+    def build_agent(body)
+      provider = Esp::Providers.build(body['provider'] || Esp::Providers.default_id, model: body['model'])
+      Esp::Agent.new(provider: provider)
+    end
+
+    def pump_agent(agent, prompt, writer)
+      agent.run(prompt) { |event| writer.write(sse(event)) }
+      writer.write(sse([:done]))
+    rescue StandardError => e
+      writer.write(sse([:error, e.message]))
+    ensure
+      writer.close
+    end
+
+    # One agent event tuple -> one SSE `data:` frame.
+    def sse(event)
+      type, *rest = event
+      data = case type
+             when :text        then { type: 'text', text: rest[0] }
+             when :tool_use    then { type: 'tool_use', name: rest[0], input: rest[1] }
+             when :tool_result then { type: 'tool_result', name: rest[0], result: rest[1] }
+             when :tool_error  then { type: 'tool_error', name: rest[0], error: rest[1][:error] }
+             when :done        then { type: 'done' }
+             else                   { type: 'error', message: rest[0] }
+             end
+      "data: #{JSON.generate(data)}\n\n"
+    end
+
+    def mount(verb, path, &handler)
+      @server.mount_proc(path) { |req, res| dispatch(req, res, verb, handler) }
+    end
+
+    def dispatch(req, res, verb, handler)
+      cors_headers(res)
+      return cors_preflight(res) if req.request_method == 'OPTIONS'
+      unless req.request_method == verb
+        return send_error(res, 405, "method not allowed (expected #{verb})",
+                          error_code: 'method_not_allowed')
+      end
+
+      send_ok(res, handler.call(parse_input(req, verb)))
+    rescue *Esp::Operations.caller_errors => e
+      send_error(res, 400, e.message, error_code: Esp::Operations.error_code(e))
+    rescue StandardError => e
+      send_error(res, 500, e.message, error_code: 'internal_error')
+    end
+
+    def cors_headers(res)
+      res['Access-Control-Allow-Origin'] = '*'
+      res['Access-Control-Allow-Methods'] = 'GET, POST, OPTIONS'
+      res['Access-Control-Allow-Headers'] = 'content-type'
+    end
+
+    def parse_input(req, method)
+      return req.query if method == 'GET'
+
+      body = req.body.to_s
+      body.empty? ? {} : JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise Esp::Operations::InputError, Esp.t('errors.http.invalid_body', message: e.message)
+    end
+
+    def cors_preflight(res)
+      res.status = 204
+    end
+
+    def send_ok(res, payload)
+      res.status = 200
+      res['Content-Type'] = 'application/json'
+      res.body = JSON.generate(payload)
+    end
+
+    def send_error(res, status, message, error_code: nil)
+      res.status = status
+      res['Content-Type'] = 'application/json'
+      body = { error: message }
+      body[:code] = error_code if error_code
+      res.body = JSON.generate(body)
+    end
+  end
+end

data/lib/esp/introspection.rb

@@ -0,0 +1,151 @@
+module Esp
+  # Builds a structured snapshot of the CLI command tree and the core
+  # library modules. Two consumers:
+  #
+  # - `esp docs build` renders this into markdown under docs/reference/.
+  # - `esp docs introspect` emits it as JSON so AI tools, ESPresso,
+  #   and the MCP server can discover capabilities at runtime.
+  #
+  # The introspection is read-only and cheap — it just walks Thor's
+  # metadata and reads each lib/esp/{,mw/}*.rb header comment block.
+  module Introspection
+    HIDDEN_COMMANDS = %w[help tree].freeze
+
+    class << self
+      def command_tree
+        walk(Esp::CLI, [])
+      end
+
+      def walk(thor_class, path)
+        reverse_map = build_reverse_map(thor_class)
+        subcommand_names = Array(thor_class.subcommands)
+
+        commands = thor_class.commands.filter_map do |name, cmd|
+          next if HIDDEN_COMMANDS.include?(name) || subcommand_names.include?(name)
+
+          display = reverse_map[name.to_s] || name.to_s
+          command_entry(display, path, cmd, thor_class)
+        end
+
+        subcommands = subcommand_names.map do |sub_name|
+          sub_class = thor_class.subcommand_classes[sub_name]
+          sub_walk = walk(sub_class, path + [sub_name])
+          {
+            name: sub_name,
+            path: path + [sub_name],
+            description: thor_class.commands[sub_name]&.description,
+            commands: sub_walk[:commands],
+            subcommands: sub_walk[:subcommands]
+          }
+        end
+
+        { commands: commands, subcommands: subcommands }
+      end
+
+      # Modules documented in docs/reference/api/. Walks both the
+      # engine-agnostic shell (lib/esp/*.rb → Esp::Foo) and the active Mw
+      # plugin (lib/esp/mw/*.rb → Esp::Mw::Foo). Skips cli.rb (the command
+      # reference covers it) and version.rb (trivial). The cli/ and
+      # providers/ subdirs are intentionally not walked here — they are
+      # subordinate to their parent modules and don't warrant their own
+      # docs pages.
+      def module_docs
+        shell = Dir.glob(File.join(Esp::ROOT, 'lib/esp/*.rb'))
+        plugin = Dir.glob(File.join(Esp::ROOT, 'lib/esp/mw/*.rb'))
+        entries_for(shell, namespace: 'Esp') + entries_for(plugin, namespace: 'Esp::Mw')
+      end
+
+      # Comment block immediately preceding the primary class/module
+      # declaration in `path`. Strips leading `# ` from each line.
+      def parse_header_comment(path)
+        lines = File.readlines(path, chomp: true)
+        target_idx = primary_declaration_index(lines)
+        return nil unless target_idx
+
+        collect_comment_above(lines, target_idx)
+      end
+
+      private
+
+      def entries_for(files, namespace:)
+        files.filter_map do |file|
+          basename = File.basename(file)
+          next if %w[cli.rb version.rb].include?(basename)
+
+          comment = parse_header_comment(file)
+          next if comment.nil? || comment.empty?
+
+          {
+            name: derive_module_name(basename, namespace: namespace),
+            source: file.sub("#{Esp::ROOT}/", ''),
+            description: comment
+          }
+        end
+      end
+
+      def command_entry(display, path, cmd, thor_class)
+        class_opts = Array(thor_class.class_options&.values).map { |o| option_data(o) }
+        cmd_opts   = Array(cmd.options.values).map { |o| option_data(o) }
+        {
+          name: display,
+          path: path + [display],
+          description: cmd.description,
+          usage: cmd.usage,
+          options: cmd_opts + class_opts
+        }
+      end
+
+      def build_reverse_map(thor_class)
+        Hash(thor_class.map).each_with_object({}) do |(alias_name, target), h|
+          h[target.to_s] = alias_name
+        end
+      end
+
+      def option_data(opt)
+        {
+          name: opt.name,
+          type: opt.type,
+          description: opt.description,
+          default: opt.default,
+          required: opt.required?,
+          aliases: Array(opt.aliases)
+        }
+      end
+
+      def primary_declaration_index(lines)
+        lines.each_with_index do |line, idx|
+          stripped = line.strip
+          next unless stripped.match?(/\A(class|module)\s+\w/)
+          # Skip the outer wrappers (`module Esp`, `module Esp::Mw`,
+          # legacy `module Mw`) to find the inner class/module that
+          # documents the file.
+          next if stripped.match?(/\A(class|module)\s+(Esp|Mw)(::|\b)/)
+
+          return idx
+        end
+        nil
+      end
+
+      def collect_comment_above(lines, target_idx)
+        out = []
+        (target_idx - 1).downto(0) do |i|
+          line = lines[i].strip
+          if line.start_with?('#')
+            out.unshift(line.sub(/\A#\s?/, ''))
+          elsif out.empty? && line.empty?
+            next
+          else
+            break
+          end
+        end
+        out.join("\n").strip
+      end
+
+      def derive_module_name(basename, namespace: 'Esp')
+        stem = File.basename(basename, '.rb')
+        camel = stem.split('_').map { |part| part.sub(/\A./, &:upcase) }.join
+        "#{namespace}::#{camel}"
+      end
+    end
+  end
+end

data/lib/esp/mcp_installer.rb

@@ -0,0 +1,122 @@
+require 'json'
+require 'fileutils'
+
+module Esp
+  # Registers `esp mcp serve` with a local MCP client by merging a stdio
+  # server entry into that client's config JSON, preserving any other servers
+  # and top-level keys already there.
+  #
+  # Deliberately kept out of Esp::Operations: rewriting a user's AI-client
+  # config is a CLI/operator action, never something an agent should be able
+  # to drive over MCP itself.
+  #
+  # The two clients share the `mcpServers` / stdio shape and an identical
+  # server entry; they differ only in where the config lives. The command is
+  # an absolute path to `bin/esp` — note `${CLAUDE_PROJECT_DIR}` looks tempting
+  # for a portable Claude Code entry but is unset when `.mcp.json` is parsed
+  # (it's a hooks-only variable), so the server silently fails to launch. The
+  # cost is a machine-specific path in the config.
+  #
+  # Step-22.5 migration: the install action quietly drops any existing entry
+  # named `mw` (the historical pre-rename name) when it writes the new `esp`
+  # entry, so a re-install after the rename leaves a single, current entry.
+  module McpInstaller
+    SERVER_NAME = 'esp'.freeze
+    LEGACY_NAME = 'mw'.freeze
+
+    Result = Struct.new(:client, :label, :config_path, :name, :action, :entry, :migrated,
+                        keyword_init: true)
+
+    CLIENTS = {
+      'claude-code' => {
+        label: 'Claude Code',
+        path: -> { File.join(Esp::ROOT, '.mcp.json') }
+      },
+      'claude-desktop' => {
+        label: 'Claude Desktop',
+        path: -> { File.expand_path('~/Library/Application Support/Claude/claude_desktop_config.json') }
+      }
+    }.freeze
+
+    class << self
+      def clients
+        CLIENTS.keys
+      end
+
+      def entry_for(client)
+        client_meta(client) # validate
+        { 'type' => 'stdio', 'command' => File.join(Esp::ROOT, 'bin', 'esp'), 'args' => %w[mcp serve] }
+      end
+
+      # Merge the entry into the client's config. +path+ overrides the default
+      # location (tests point it at a tmpfile). Returns a Result whose :action
+      # is :created / :updated / :unchanged. The :migrated flag is true when
+      # this install removed a legacy `mw` entry pointing at the same install.
+      def install(client, name: SERVER_NAME, path: nil)
+        meta = client_meta(client)
+        config_path = path || meta[:path].call
+        entry = entry_for(client)
+        config = read_config(config_path)
+        servers = (config['mcpServers'] ||= {})
+        migrated = migrate_legacy_entry(servers, name)
+        action = action_for(servers[name], entry)
+        servers[name] = entry
+        write_config(config_path, config) unless action == :unchanged && !migrated
+        Result.new(client: client, label: meta[:label], config_path: config_path,
+                   name: name, action: action, entry: entry, migrated: migrated)
+      end
+
+      private
+
+      # Drop the legacy `mw` entry when installing the new `esp` entry under a
+      # different name, so a user doesn't end up with both. We only remove
+      # when the legacy entry looks like a previous install of this same tool
+      # (its command resolves to a `bin/mw` path) — never blindly delete an
+      # entry the user might have wired by hand. Skipped when the caller asks
+      # for `name: LEGACY_NAME` (an explicit re-pin to the old name).
+      def migrate_legacy_entry(servers, name)
+        return false if name == LEGACY_NAME
+        return false unless (legacy = servers[LEGACY_NAME])
+        return false unless legacy.is_a?(Hash) && legacy['command'].to_s.end_with?('/bin/mw')
+
+        servers.delete(LEGACY_NAME)
+        true
+      end
+
+      def client_meta(client)
+        CLIENTS.fetch(client) do
+          raise ArgumentError, Esp.t('errors.mcp_installer.unknown_client',
+                                     client: client, clients: clients.join(', '))
+        end
+      end
+
+      def read_config(path)
+        return {} unless File.exist?(path)
+
+        content = File.read(path).strip
+        return {} if content.empty?
+
+        parsed = JSON.parse(content)
+        unless parsed.is_a?(Hash)
+          raise ArgumentError, Esp.t('errors.mcp_installer.not_json_object', path: path)
+        end
+
+        parsed
+      rescue JSON::ParserError => e
+        raise ArgumentError, Esp.t('errors.mcp_installer.invalid_json', path: path, message: e.message)
+      end
+
+      def write_config(path, config)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, "#{JSON.pretty_generate(config)}\n")
+      end
+
+      def action_for(existing, entry)
+        return :created if existing.nil?
+        return :unchanged if existing == entry
+
+        :updated
+      end
+    end
+  end
+end