chocomint 1.0.0

data/lib/chocomint/edit_handlers.rb

@@ -0,0 +1,696 @@
+# frozen_string_literal: true
+
+require "json"
+require "cgi"
+require "set"
+
+module Chocomint
+  # /edit AI エディタの HTTP ハンドラ群 (Server に include して使う)。
+  #
+  # 提供機能:
+  #   GET  /edit            エディタ画面 (メニュー/ファイル一覧/Monaco/AIチャット/コンソール)
+  #   GET  /edit/assets/*   Monaco / xterm.js のローカル同梱アセット配信
+  #   GET  /edit/static/*   自前の CSS/JS 配信 (public/edit/)
+  #   GET  /edit/files      workspace のファイル一覧 (JSON)
+  #   GET  /edit/file?path= ファイル内容 (JSON)
+  #   POST /edit/save       ファイル保存 (PathGuard で workspace 内に限定)
+  #   POST /edit/chat       自然言語指示で AI 編集 (Planner が提案→実行→検証→再試行)
+  #
+  # ファイルアクセスはすべて @path_guard 経由で許可ディレクトリ内に制限する。
+  module EditHandlers
+    # workspace ルート (allowed_roots の先頭)。表示・列挙の起点にする。
+    def edit_root
+      @path_guard.allowed_roots.first
+    end
+
+    # ---- ファイル一覧 -------------------------------------------------------
+
+    def handle_edit_files(req, res)
+      return edit_method_guard(res) unless req.request_method == "GET"
+
+      entries = list_workspace_files
+      edit_json(res, 200, "files" => entries, "dirs" => list_workspace_empty_dirs(entries),
+                           "root" => relative_root, "abs_root" => edit_root.tr("\\", "/"))
+    rescue Chocomint::Error => e
+      edit_json(res, 500, "error" => e.message)
+    end
+
+    # workspace 配下を再帰列挙し、相対パスの配列で返す (ディレクトリは除く)。
+    MAX_LISTED_FILES = 2000
+
+    # 中身を展開しない VCS メタデータ・依存パッケージ等 (数千件で一覧を埋め尽くすため除外する)。
+    EXCLUDED_TREE_DIRS = %w[.git .hg .svn .venv venv node_modules .bundle vendor/bundle].freeze
+
+    def list_workspace_files
+      root = edit_root
+      return [] unless File.directory?(root)
+
+      files = []
+      # File::FNM_DOTMATCH で "." 始まりの隠しファイル/ディレクトリも列挙対象に含める。
+      Dir.glob("**/*", File::FNM_DOTMATCH, base: root).each do |rel|
+        rel = rel.tr("\\", "/")
+        # "." / ".." など自己・親参照は除外する (FNM_DOTMATCH で拾われるため)。
+        next if [".", ".."].include?(File.basename(rel))
+        # .git などの配下は展開しない (メタデータで一覧が埋まるのを防ぐ)。
+        next if EXCLUDED_TREE_DIRS.any? { |d| rel == d || rel.start_with?("#{d}/") }
+
+        abs = File.join(root, rel)
+        next unless File.file?(abs)
+
+        files << rel
+        break if files.size >= MAX_LISTED_FILES
+      end
+      files.sort
+    end
+
+    # files に1件も含まれないディレクトリ (空ディレクトリ、または空ディレクトリのみを含むディレクトリ) を列挙する。
+    # ファイル一覧からはツリー構築できないため、これらを別途フロントエンドに伝えてツリーに表示させる。
+    def list_workspace_empty_dirs(files)
+      root = edit_root
+      return [] unless File.directory?(root)
+
+      covered = files.each_with_object(Set.new) do |rel, set|
+        parts = rel.split("/")
+        parts.pop
+        prefix = +""
+        parts.each do |part|
+          prefix = prefix.empty? ? part : "#{prefix}/#{part}"
+          set << prefix
+        end
+      end
+
+      dirs = []
+      Dir.glob("**/*", File::FNM_DOTMATCH, base: root).each do |rel|
+        rel = rel.tr("\\", "/")
+        next if [".", ".."].include?(File.basename(rel))
+        next if EXCLUDED_TREE_DIRS.any? { |d| rel == d || rel.start_with?("#{d}/") }
+        next if covered.include?(rel)
+
+        abs = File.join(root, rel)
+        next unless File.directory?(abs)
+
+        dirs << rel
+        break if dirs.size >= MAX_LISTED_FILES
+      end
+      dirs.sort
+    end
+
+    # ---- ファイル取得 -------------------------------------------------------
+
+    def handle_edit_file(req, res)
+      return edit_method_guard(res) unless req.request_method == "GET"
+
+      path = req.query["path"].to_s
+      return edit_json(res, 400, "error" => "path required") if path.empty?
+
+      abs = @path_guard.resolve(path)
+      return edit_json(res, 404, "error" => "no such file") unless File.file?(abs)
+      if File.size(abs) > @max_file_bytes
+        return edit_json(res, 413, "error" => "file too large")
+      end
+
+      raw = File.read(abs, mode: "rb")
+      # テキストとして開けない (バイナリ / 不正な UTF-8) ファイルは中身を返さずフラグで知らせる。
+      if binary_content?(raw)
+        return edit_json(res, 200, "path" => path, "binary" => true)
+      end
+
+      edit_json(res, 200, "path" => path, "content" => raw.force_encoding("UTF-8"))
+    rescue Chocomint::PathAccessError => e
+      edit_json(res, 403, "error" => e.message)
+    rescue Chocomint::Error => e
+      edit_json(res, 500, "error" => e.message)
+    end
+
+    # テキストとして扱えないか判定する。NUL バイトを含む、または先頭ブロックが
+    # 妥当な UTF-8 でないものはバイナリ (エディタで開けない) とみなす。
+    BINARY_SNIFF_BYTES = 8192
+
+    def binary_content?(raw)
+      return false if raw.empty?
+
+      head = raw.byteslice(0, BINARY_SNIFF_BYTES)
+      return true if head.include?("\x00")
+
+      !head.dup.force_encoding("UTF-8").valid_encoding?
+    end
+
+    # ---- 保存 (人手編集) ----------------------------------------------------
+
+    def handle_edit_save(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      body = JSON.parse(req.body.to_s)
+      path = body["path"].to_s
+      content = body["content"].to_s
+      return edit_json(res, 400, "error" => "path required") if path.empty?
+      if content.bytesize > @max_file_bytes
+        return edit_json(res, 413, "error" => "content exceeds max_file_bytes")
+      end
+
+      abs = @path_guard.resolve(path)
+      FileUtils.mkdir_p(File.dirname(abs))
+      File.write(abs, content)
+      edit_json(res, 200, "path" => path, "bytes" => content.bytesize)
+    rescue JSON::ParserError => e
+      edit_json(res, 400, "error" => "invalid JSON: #{e.message}")
+    rescue Chocomint::PathAccessError => e
+      edit_json(res, 403, "error" => e.message)
+    rescue Chocomint::Error => e
+      edit_json(res, 500, "error" => e.message)
+    end
+
+    # ---- AI 編集 (チャット) -------------------------------------------------
+
+    def handle_edit_chat(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      body = JSON.parse(req.body.to_s)
+      instruction = body["instruction"].to_s.strip
+      path = body["path"].to_s
+      return edit_json(res, 400, "error" => "instruction required") if instruction.empty?
+
+      # stream=true なら SSE でツール実行の進捗を逐次配信する (UI のリアルタイム表示用)。
+      return handle_edit_chat_stream(res, instruction, path) if body["stream"]
+
+      # ツール不要の普通の質問なら会話として直接応答する。それ以外は Planner に流す。
+      if chat_instruction?(instruction)
+        return edit_json(res, 200, edit_chat_reply(instruction, path))
+      end
+
+      request = build_chat_request(path, instruction)
+      result = @planner.run(request, expectations: instruction)
+      edit_json(res, 200, edit_chat_result(result, path, instruction))
+    rescue JSON::ParserError => e
+      edit_json(res, 400, "error" => "invalid JSON: #{e.message}")
+    rescue Chocomint::InvalidProposalError, Chocomint::UnknownToolError => e
+      edit_json(res, 422, "status" => "FAIL", "error" => humanize_chat_error(e))
+    rescue Chocomint::RetryLimitExceededError => e
+      edit_json(res, 200, "status" => "FAIL", "error" => humanize_chat_error(e), "steps" => [])
+    rescue Chocomint::Error => e
+      edit_json(res, 500, "error" => e.message)
+    end
+
+    # SSE 版のチャット処理。Planner のステップ進捗を逐次 event として流し、
+    # 最後に従来の JSON 結果を "result" event として送って締める。
+    # イベント: tool_start / tool_done / result / error (data は JSON 1 行)。
+    def handle_edit_chat_stream(res, instruction, path)
+      res.status = 200
+      res["content-type"] = "text/event-stream; charset=utf-8"
+      res["cache-control"] = "no-cache"
+      res.chunked = true
+      res.body = lambda do |out|
+        emit_sse = ->(event, data) { out.write("event: #{event}\ndata: #{JSON.generate(deep_scrub(data))}\n\n") }
+        begin
+          run_chat_stream(instruction, path, emit_sse)
+        rescue Chocomint::InvalidProposalError, Chocomint::UnknownToolError,
+               Chocomint::RetryLimitExceededError => e
+          emit_sse.call("result", "status" => "FAIL", "error" => humanize_chat_error(e), "steps" => [])
+        rescue Chocomint::Error => e
+          emit_sse.call("error", "error" => e.message)
+        end
+      end
+    end
+
+    # SSE 本体: 会話 or Planner 実行を行い、進捗と最終結果を emit_sse で送る。
+    def run_chat_stream(instruction, path, emit_sse)
+      # 会話 (ツール不要) は進捗が無いので、そのまま最終結果だけ送る。
+      if chat_instruction?(instruction)
+        emit_sse.call("result", edit_chat_reply(instruction, path))
+        return
+      end
+
+      request = build_chat_request(path, instruction)
+      on_event = lambda do |ev|
+        case ev[:type]
+        when "step_start"
+          emit_sse.call("tool_start",
+                        "step" => ev[:step],
+                        "tool" => ev[:tool],
+                        "label" => tool_label(ev[:tool]),
+                        "target" => tool_target_summary(ev[:tool], ev[:arguments]))
+        when "step_done"
+          ok = ev[:status] == "PASS" && (result_field(ev[:result], :exit_code).nil? ||
+                                         result_field(ev[:result], :exit_code) == 0)
+          emit_sse.call("tool_done",
+                        "step" => ev[:step],
+                        "tool" => ev[:tool],
+                        "label" => tool_label(ev[:tool]),
+                        "target" => tool_target_summary(ev[:tool], ev[:arguments]),
+                        "status" => ev[:status],
+                        "ok" => ok,
+                        "exit_code" => result_field(ev[:result], :exit_code),
+                        # 実行結果 (stdout/stderr など) を人が読める形にして都度表示させる。
+                        "output" => tool_output_text(ev[:result]))
+        end
+      end
+
+      result = @planner.run(request, expectations: instruction, on_event: on_event)
+      emit_sse.call("result", edit_chat_result(result, path, instruction))
+    end
+
+    # Planner の例外メッセージ (英語) を UI 向けの日本語に言い換える。
+    # 原文は握りつぶさず末尾に括弧書きで残す (デバッグの手がかりのため)。
+    def humanize_chat_error(err)
+      case err
+      when Chocomint::RetryLimitExceededError
+        "指示を達成できませんでした。指示をより具体的にするか、手順を分けて試してください。"
+      when Chocomint::InvalidProposalError
+        "AI が実行するツールをうまく選べませんでした。指示を言い換えて試してください。"
+      when Chocomint::UnknownToolError
+        "AI が存在しないツールを呼び出そうとしました。指示を言い換えて試してください。"
+      else
+        "エラーが発生しました。"
+      end + " (#{err.message})"
+    end
+
+    # ---- 会話ログの圧縮 (/compact) -----------------------------------------
+    #
+    # ブラウザから現在のチャット表示テキストを受け取り、AI に要点を要約させて返す。
+    # サーバー側は会話履歴を保持しないため、これは「表示ログを短い要約 1 件に畳む」
+    # ための機能 (AI の文脈には元々影響しない)。chat_client 未注入なら 503。
+
+    # 要約に渡すログの上限 (これを超える古い部分は末尾を優先して切り詰める)。
+    COMPACT_INPUT_LIMIT = 12_000
+
+    def handle_edit_compact(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+      return edit_json(res, 503, "error" => "chat client not configured") unless @chat_client
+
+      body = JSON.parse(req.body.to_s)
+      transcript = body["transcript"].to_s.strip
+      return edit_json(res, 400, "error" => "transcript required") if transcript.empty?
+
+      # 長すぎる場合は新しい方 (末尾) を優先して残す。
+      if transcript.length > COMPACT_INPUT_LIMIT
+        transcript = "（以前のやり取りは省略）\n#{transcript[-COMPACT_INPUT_LIMIT..]}"
+      end
+
+      summary = @chat_client.compact(transcript)
+      edit_json(res, 200, "summary" => summary)
+    rescue JSON::ParserError => e
+      edit_json(res, 400, "error" => "invalid JSON: #{e.message}")
+    rescue Chocomint::Error => e
+      edit_json(res, 500, "error" => e.message)
+    end
+
+    # chat_client があり、指示が「会話」と分類されたときだけ会話として扱う。
+    # chat_client 未注入なら常に false (従来どおり全て Planner に流す)。
+    def chat_instruction?(instruction)
+      return false unless @chat_client
+
+      @chat_client.classify(instruction) == "chat"
+    rescue Chocomint::Error
+      # 分類に失敗したら安全側でタスク扱い (Planner に流す)。
+      false
+    end
+
+    # 会話 (普通の質問) への直接応答を UI 向け JSON に整形する。
+    # 開いているファイルがあれば内容を文脈として渡す。
+    def edit_chat_reply(instruction, path)
+      answer = @chat_client.answer(instruction, context: chat_file_context(path))
+      { "status" => "PASS", "reply" => answer, "steps" => [] }
+    rescue Chocomint::Error => e
+      { "status" => "FAIL", "error" => e.message, "steps" => [] }
+    end
+
+    # 会話の文脈として渡すファイル内容 (先頭のみ)。開いていない/読めない場合は nil。
+    CHAT_CONTEXT_LIMIT = 4000
+
+    def chat_file_context(path)
+      return nil if path.empty?
+
+      abs = @path_guard.resolve(path)
+      return nil unless File.file?(abs)
+
+      content = File.read(abs, mode: "rb").force_encoding("UTF-8")
+      content = "#{content[0, CHAT_CONTEXT_LIMIT]}…" if content.length > CHAT_CONTEXT_LIMIT
+      "現在開いているファイル #{path} の内容:\n```\n#{content}\n```"
+    rescue Chocomint::Error
+      nil
+    end
+
+    # 対象ファイルがあれば文脈として明示し、無ければ指示だけを渡す。
+    def build_chat_request(path, instruction)
+      if path.empty?
+        instruction
+      else
+        "ファイル #{path} に対して次の指示を反映してください: #{instruction}"
+      end
+    end
+
+    # Planner::Result を UI 向けの JSON に整形する。編集後内容も返して Monaco を更新する。
+    # instruction: 要約生成のための元の要求文 (任意)。
+    def edit_chat_result(result, path, instruction = nil)
+      steps = result.steps.map do |s|
+        r = s[:result]
+        { "tool" => s[:tool],
+          # UI で読みやすい日本語ラベル (例: "コマンド実行")。
+          "label" => tool_label(s[:tool]),
+          "arguments" => s[:arguments],
+          # 引数の 1 行要約 (例: どのファイル / どのコマンドを対象にしたか)。
+          "target" => tool_target_summary(s[:tool], s[:arguments]),
+          "status" => s[:status],
+          # ツールの終了コード (0 = 成功)。シンボル/文字列どちらのキーでも拾う。
+          "exit_code" => result_field(r, :exit_code),
+          # ツールの実行結果 (stdout / 生成物など) を人間可読テキストにして返す。
+          "output" => tool_output_text(r) }
+      end
+      payload = {
+        "status" => result.status,
+        "trace_id" => result.trace_id,
+        "attempts" => result.attempts,
+        "steps" => steps
+      }
+      # 要約 (summary) と注記 (note) の振り分け。
+      #  - ステップ無し + message: 聞き返し・会話的回答。message をそのまま要約枠に出す
+      #    (実行内容が無いので summarize しない)。
+      #  - ステップ有り + incomplete: 未完了の注記 (message) は黄色の注記枠へ。要約は別途生成する。
+      #  - ステップ有り + 通常の finish message: それを要約として使う (summarize の代わり)。
+      #  - それ以外のステップ有り: AI に実行内容を要約させる。
+      if !result.message.to_s.empty? && steps.empty?
+        payload["summary"] = result.message
+      elsif result.incomplete
+        payload["note"] = result.message unless result.message.to_s.empty?
+        if @chat_client && !steps.empty? && instruction
+          summary = @chat_client.summarize(instruction, steps, trace_id: result.trace_id)
+          payload["summary"] = summary if summary
+        end
+      elsif !result.message.to_s.empty? && !steps.empty?
+        payload["summary"] = result.message
+      elsif @chat_client && result.status == "PASS" && !steps.empty? && instruction
+        summary = @chat_client.summarize(instruction, steps, trace_id: result.trace_id)
+        payload["summary"] = summary if summary
+      end
+      # 対象ファイルがまだ存在すれば最新内容を返す (AI が編集した結果を反映)。
+      unless path.empty?
+        begin
+          abs = @path_guard.resolve(path)
+          payload["content"] = File.read(abs) if File.file?(abs)
+        rescue Chocomint::Error
+          # 解決できない・消えた等は content 無しで返す。
+        end
+      end
+      payload
+    end
+
+    # ツール実行結果を UI 表示用のテキストに整形する。ハッシュなら stdout/stderr など
+    # 人が読みたいキーを優先する。結果ハッシュのキーはツール実装ではシンボル
+    # ({ exit_code:, stdout:, ... })、テスト等では文字列で来るため両対応にする。
+    # 該当キーが空なら nil を返し (生 JSON は出さない)、UI 側で「(出力なし)」を表示させる。
+    # PowerShell 等の色付き出力に含まれる ANSI エスケープは、そのまま出すと文字化けに
+    # 見えるため除去する。
+    def tool_output_text(result)
+      text =
+        case result
+        when nil then nil
+        when String then result
+        when Hash
+          joined = %i[stdout stderr message content]
+                   .map { |k| result_field(result, k) }
+                   .compact.map(&:to_s).reject(&:empty?).join("\n")
+          joined.empty? ? nil : joined
+        else
+          result.to_s
+        end
+      text.nil? ? nil : strip_ansi(text)
+    end
+
+    # ANSI エスケープシーケンス (色・装飾。CSI \e[...m 等) を取り除く。
+    # 端末を経由しない chocomint の出力表示では色コードは無意味で、文字化けに見えるだけ。
+    ANSI_ESCAPE = /\e\[[0-9;?]*[ -\/]*[@-~]/
+
+    def strip_ansi(text)
+      text.gsub(ANSI_ESCAPE, "")
+    end
+
+    # 結果ハッシュからキー key の値を取り出す (シンボル/文字列どちらのキーでも拾う)。
+    def result_field(result, key)
+      return nil unless result.is_a?(Hash)
+
+      result.fetch(key) { result[key.to_s] }
+    end
+
+    # 内部ツール名を UI 向けの日本語ラベル (アイコン付き) に変換する。未知の名前は原文。
+    TOOL_LABELS = {
+      "write_file" => "📝 ファイル書き込み",
+      "read_file" => "📖 ファイル読み取り",
+      "append_file" => "➕ ファイル追記",
+      "delete_file" => "🗑 ファイル削除",
+      "edit" => "✏️ ファイル編集",
+      "make_dir" => "📁 ディレクトリ作成",
+      "file_info" => "ℹ️ ファイル情報",
+      "list_dir" => "📂 ディレクトリ一覧",
+      "ls" => "📂 一覧表示",
+      "glob" => "🔍 ファイル検索",
+      "grep" => "🔍 内容検索",
+      "run_command" => "▶️ コマンド実行",
+      "bash" => "▶️ コマンド実行",
+      "shell" => "▶️ コマンド実行"
+    }.freeze
+
+    def tool_label(tool)
+      TOOL_LABELS.fetch(tool.to_s, "🔧 #{tool}")
+    end
+
+    # 引数から「何を対象にしたか」を 1 行で要約する (例: 対象ファイル名 / 実行コマンド)。
+    TARGET_SUMMARY_LIMIT = 120
+
+    def tool_target_summary(tool, args)
+      return nil unless args.is_a?(Hash)
+
+      value =
+        case tool.to_s
+        when "run_command", "bash", "shell"
+          args["command"] || args["cmd"] || args["script"]
+        when "grep", "glob"
+          args["pattern"] || args["path"]
+        else
+          args["path"] || args["file"] || args["dir"]
+        end
+      return nil if value.nil?
+
+      s = value.to_s.gsub(/\s+/, " ").strip
+      s.length > TARGET_SUMMARY_LIMIT ? "#{s[0, TARGET_SUMMARY_LIMIT]}…" : s
+    end
+
+    # ---- ファイル操作 (右クリックメニュー) ---------------------------------
+    #
+    # いずれも @path_guard.resolve を通し workspace 外を拒否する。相対パスは
+    # 一覧と同じく "/" 区切りで受け取る。
+
+    # ファイル or ディレクトリを削除する。
+    def handle_edit_fs_delete(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      with_fs(res) do
+        path = fs_body_path(req)
+        abs = @path_guard.resolve(path)
+        raise Chocomint::Error, "workspace ルートは削除できません" if abs == edit_root
+        raise Chocomint::Error, "no such path" unless File.exist?(abs)
+
+        FileUtils.rm_rf(abs)
+        edit_json(res, 200, "path" => path, "deleted" => true)
+      end
+    end
+
+    # ファイル or ディレクトリの名前変更 (移動)。to は同一 workspace 内に限る。
+    def handle_edit_fs_rename(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      with_fs(res) do
+        body = JSON.parse(req.body.to_s)
+        from = normalize_fs_path(body["from"])
+        to = normalize_fs_path(body["to"])
+        raise Chocomint::Error, "from/to required" if from.empty? || to.empty?
+
+        src = @path_guard.resolve(from)
+        dst = @path_guard.resolve(to)
+        raise Chocomint::Error, "no such path" unless File.exist?(src)
+        raise Chocomint::Error, "移動先が既に存在します" if File.exist?(dst)
+
+        FileUtils.mkdir_p(File.dirname(dst))
+        FileUtils.mv(src, dst)
+        edit_json(res, 200, "from" => from, "to" => to)
+      end
+    end
+
+    # ディレクトリを新規作成する (親が無ければ一緒に作る)。
+    def handle_edit_fs_mkdir(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      with_fs(res) do
+        path = fs_body_path(req)
+        abs = @path_guard.resolve(path)
+        raise Chocomint::Error, "既に存在します" if File.exist?(abs)
+
+        FileUtils.mkdir_p(abs)
+        edit_json(res, 200, "path" => path, "created" => true)
+      end
+    end
+
+    # 空ファイルを新規作成する (親ディレクトリが無ければ作る)。
+    def handle_edit_fs_touch(req, res)
+      return edit_method_guard(res) unless req.request_method == "POST"
+
+      with_fs(res) do
+        path = fs_body_path(req)
+        abs = @path_guard.resolve(path)
+        raise Chocomint::Error, "既に存在します" if File.exist?(abs)
+
+        FileUtils.mkdir_p(File.dirname(abs))
+        File.write(abs, "")
+        edit_json(res, 200, "path" => path, "created" => true)
+      end
+    end
+
+    # ---- ファイル操作の補助 -------------------------------------------------
+
+    # JSON ボディから正規化済みの "path" を取り出す (空なら 400 相当の例外)。
+    def fs_body_path(req)
+      body = JSON.parse(req.body.to_s)
+      path = normalize_fs_path(body["path"])
+      raise Chocomint::Error, "path required" if path.empty?
+
+      path
+    end
+
+    # バックスラッシュを "/" に統一し前後空白を除く。
+    def normalize_fs_path(value)
+      value.to_s.tr("\\", "/").strip
+    end
+
+    # ファイル操作系ハンドラ共通の例外→HTTP 変換。
+    def with_fs(res)
+      yield
+    rescue JSON::ParserError => e
+      edit_json(res, 400, "error" => "invalid JSON: #{e.message}")
+    rescue Chocomint::PathAccessError => e
+      edit_json(res, 403, "error" => e.message)
+    rescue Chocomint::Error => e
+      edit_json(res, 400, "error" => e.message)
+    rescue SystemCallError => e
+      edit_json(res, 500, "error" => e.message)
+    end
+
+    # ---- アセット配信 -------------------------------------------------------
+
+    ASSET_CONTENT_TYPES = {
+      ".js" => "application/javascript; charset=utf-8",
+      ".css" => "text/css; charset=utf-8",
+      ".ttf" => "font/ttf",
+      ".map" => "application/json",
+      ".svg" => "image/svg+xml",
+      ".html" => "text/html; charset=utf-8"
+    }.freeze
+
+    def handle_edit_asset(req, res)
+      return edit_method_guard(res) unless req.request_method == "GET"
+
+      # /edit/assets/<rel> の <rel> を取り出し、vendor 配下限定で配信する (Monaco / xterm.js)。
+      # vendor は不変の大容量アセットなので長期キャッシュしてよい。
+      serve_edit_static(req, res, prefix: "/edit/assets/", root: @vendor_dir,
+                                  cache: "public, max-age=86400")
+    end
+
+    def handle_edit_static(req, res)
+      return edit_method_guard(res) unless req.request_method == "GET"
+
+      # /edit/static/<rel> の <rel> を取り出し、public/edit 配下限定で配信する (自前の CSS/JS)。
+      # 自前の CSS/JS は開発中に頻繁に編集するため、キャッシュせず毎回最新を配信する。
+      serve_edit_static(req, res, prefix: "/edit/static/", root: @edit_static_dir,
+                                  cache: "no-cache")
+    end
+
+    # prefix を取り除いた相対パスを root 配下限定で解決して配信する共通ロジック。
+    def serve_edit_static(req, res, prefix:, root:, cache:)
+      rel = req.path.sub(%r{\A#{Regexp.escape(prefix)}}, "")
+      abs = File.expand_path(rel, root)
+      # traversal 防止: root の外を指したら拒否。
+      unless abs.start_with?(root + File::SEPARATOR) || abs == root
+        res.status = 403
+        res.body = "forbidden"
+        return
+      end
+      unless File.file?(abs)
+        res.status = 404
+        res.body = "not found"
+        return
+      end
+
+      res.status = 200
+      res["content-type"] = ASSET_CONTENT_TYPES.fetch(File.extname(abs), "application/octet-stream")
+      res["cache-control"] = cache
+      res.body = File.binread(abs)
+    end
+
+    # ---- エディタ画面 -------------------------------------------------------
+
+    def handle_edit(req, res)
+      return edit_method_guard(res) unless req.request_method == "GET"
+
+      res.status = 200
+      res["content-type"] = "text/html; charset=utf-8"
+      # HTML は常に最新を返す (ブラウザのヒューリスティックキャッシュで古い版が
+      # 残ると CSS/JS の参照や DOM 構造がずれるため)。
+      res["cache-control"] = "no-cache"
+      res.body = edit_html
+    end
+
+    # ---- 補助 ---------------------------------------------------------------
+
+    def relative_root
+      rel = edit_root.sub(/\A#{Regexp.escape(@base_dir)}[\\\/]?/, "")
+      rel.empty? ? "." : rel.tr("\\", "/")
+    end
+
+    def edit_json(res, status, hash)
+      res.status = status
+      res["content-type"] = "application/json"
+      # ツール出力 (外部プロセスの stdout など) は妥当な UTF-8 とは限らない。
+      # 不正バイトが混じると JSON.generate が例外を投げ、WEBrick が HTML の 500 を
+      # 返してしまう (フロントは JSON を期待して "Unexpected token '<'" になる)。
+      # 生成前に全文字列を UTF-8 として scrub し、無効バイトを U+FFFD に置換して守る。
+      res.body = JSON.generate(deep_scrub(hash))
+    end
+
+    # ハッシュ/配列/文字列を再帰的にたどり、文字列を妥当な UTF-8 に正規化する。
+    # UTF-8 以外のエンコーディング (ASCII-8BIT な外部プロセス出力等) も UTF-8 とみなして
+    # scrub し、変換不能なバイトは置換文字にする。ハッシュのキーも同様に正規化する。
+    def deep_scrub(value)
+      case value
+      when String
+        s = value.encoding == Encoding::UTF_8 ? value : value.dup.force_encoding("UTF-8")
+        s.valid_encoding? ? s : s.scrub("�")
+      when Hash
+        value.each_with_object({}) { |(k, v), h| h[deep_scrub(k)] = deep_scrub(v) }
+      when Array
+        value.map { |v| deep_scrub(v) }
+      else
+        value
+      end
+    end
+
+    def edit_method_guard(res)
+      res.status = 405
+      res["content-type"] = "application/json"
+      res.body = JSON.generate("error" => "method not allowed")
+    end
+
+    # WebSocket コンソールの接続先。ws_port 未設定ならコンソール無効。
+    def console_ws_config
+      return nil unless @ws_port
+
+      { "port" => @ws_port, "token" => @ws_token }
+    end
+
+    def edit_html
+      ws = console_ws_config
+      ws_json = ws ? JSON.generate(ws) : "null"
+      EDIT_HTML_TEMPLATE.sub("__WS_CONFIG__", ws_json)
+    end
+  end
+end
+
+require_relative "edit_html"
+require "fileutils"