chocomint 1.0.3 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43fbe75bcf172909a002314dbbd673417c25e2ab667f3e401eacb026988743e4
-  data.tar.gz: 68e6a6bf6ecd91251f5311a6c03742353e17ac4689c51b64cd35fe1d602e80f2
+  metadata.gz: cf5b5e18513023f06550376aa901ada01d10efd621f53fc01c4f1671b94e3f1d
+  data.tar.gz: 8fa2badc83ba90c08fd8bcbc5a2a2632a4342993befafb3721457e10c39ee168
 SHA512:
-  metadata.gz: ec1a8f844e984a0387bd6d2a22d66af477b99c6d99320904cc870a2bc115b7b9a3dd21135cab14a966920634f957f9b65657b1abe376d05c28b6e28a113408da
-  data.tar.gz: 9b8726ba1954c4eded4eaf811ed58c6c6db2ecb239286cb85b98be6263aefe11cdbea98e017a90b8a843495834ae385690b7cc0d3e0ccd00299c2f56b4e2846d
+  metadata.gz: 6be492f0a271ab2d6978da7c22c6740522983f933f167b96fcdc7800482b341aadc48156d4cb062612abadda090dcc34220a4f0e21745e2b835c51e0a658f8fb
+  data.tar.gz: b5408738a6734a31b1d311fa455c4f2374f176c375cd6fddb7136011353c8fe7dddd54461851baf2c7ed625c6091f7a3d36e90e30ea71a6d918eda31a66ebd0d

data/README.md

@@ -27,7 +27,14 @@ bundle install
 
 ## 設定
 
-`config/config.yml` を編集する（DESIGN §11）。実機確認済みの構成:
+設定ファイルは XDG Base Directory 準拠のユーザーパスに置かれる:
+
+- `~/.config/chocomint/config.yaml`（`$XDG_CONFIG_HOME` があればそちらの `chocomint/config.yaml`）
+
+初回起動時、このファイルが無ければ gem 同梱の既定 `config/config.yml` が上記へ
+コピーされる。以後はユーザーパス側を編集する（`/edit` のモデル切り替えもここへ保存される）。
+
+実機確認済みの構成:
 
 ```yaml
 llm:
@@ -191,11 +198,37 @@ ruby bin/chocomint-server
 |----------------|------|
 | `GET /edit` | エディタ画面 |
 | `GET /edit/files` | `workspace/` のファイル一覧 (JSON) |
-| `GET /edit/file?path=` | ファイル内容 (JSON) |
+| `GET /edit/file?path=` | ファイル内容 (JSON)。画像/PDF/動画/音声は `media` 種別だけ返す |
+| `GET /edit/raw?path=` | 生ファイル配信（メディアプレビュー用。`Range` 対応で動画のシークも可） |
+| `GET /edit/archive?path=` | アーカイブの第一階層エントリ + メタデータ（zip / tar / tar.gz / bz2 等） |
 | `POST /edit/save` | 人手編集の保存（`PathGuard` で `workspace/` 内に限定） |
 | `POST /edit/chat` | 自然言語指示で AI 編集（`Planner#run`。`expectations` に指示を渡すため意味的検証が効く） |
 | `GET /edit/assets/*` | Monaco / xterm.js のローカル同梱アセット |
 
+### メディアプレビュー
+
+テキストファイルは Monaco で編集し、以下のメディアはタブ内でプレビューする
+（`workspace/` 配下のみ・`PathGuard` で保護）:
+
+- **画像**: PNG / JPEG / GIF / WebP / BMP / ICO / AVIF / TIFF / SVG（ベクター）
+- **文書**: PDF（ブラウザ内蔵ビューアで表示）
+- **動画**: MP4 / WebM / MKV / MOV / AVI / OGV（`<video>`。ブラウザが対応する形式のみ再生可）
+- **音声**: MP3 / WAV / OGG / M4A / AAC / FLAC / Opus（`<audio>`）
+
+動画・音声は `Range` リクエストに対応し、シークやストリーミング再生ができる。
+ブラウザがコーデック非対応の形式（MKV の一部など）は再生できずメッセージを表示する。
+
+### アーカイブプレビュー
+
+zip / tar 系アーカイブをクリックすると、**第一階層（トップレベル）のエントリと
+メタデータ**（エントリ数・展開後サイズ・圧縮サイズ）をタブ内に表示する。展開は
+サーバー側でメモリ上に行い、ディスクには書き出さない。
+
+- **対応**: `.zip` / `.tar` / `.tar.gz`（`.tgz`）/ `.gz` / `.tar.bz2`（`.tbz2`）/ `.bz2`
+- 配下のエントリは親ディレクトリに畳み、その配下件数を添えて表示する。
+- `.zip` は中央ディレクトリを自前パースするため rubyzip 非依存。`.bz2` は純Ruby
+  実装の `rbzip2` で展開する（ネイティブ `libbz2` 不要）。
+
 ### 追加依存
 
 - `ffi` — Windows の擬似コンソール (ConPTY) を FFI で叩く（プリビルド gem、DevKit 不要）。

data/THIRD_PARTY_LICENSES.md

@@ -41,5 +41,6 @@ AI エディタ (`/edit`) をオフラインで動作させるため、以下を
 | webrick | Ruby / BSD-2-Clause | https://github.com/ruby/webrick |
 | ffi | BSD-3-Clause | https://github.com/ffi/ffi |
 | websocket-driver | Apache-2.0 | https://github.com/faye/websocket-driver-ruby |
+| rbzip2 | BSD-3-Clause | https://github.com/koraktor/rbzip2 |
 
 上記はいずれも再配布・商用利用を許容する寛容なライセンスである。

data/bin/chocomint-server

@@ -39,5 +39,6 @@ Chocomint::Server.new(
   max_file_bytes: config.max_file_bytes,
   ws_port: ws_port,
   ws_token: ws_token,
-  chat_client: chat_client
+  chat_client: chat_client,
+  config: config
 ).start

data/config/config.yml

@@ -1,37 +1,39 @@
-# chocomint 設定 (DESIGN.md §11)
-llm:
-  base_url: http://localhost:11434/v1
-  model: gemma4:e4b
-  api_key_env: OLLAMA_API_KEY   # 参照する環境変数名 (無ければ空)
-  max_tokens: 4096               # thinking モデルは思考だけで使い切ることがあるため余裕を持たせる
-
-verifier:
-  enabled: true
-  # モデルは指定しない。VRAM 節約のため llm.model を共有する (factory.rb 参照)。
-  max_tokens: 1024                # thinking モデルは思考だけで使い切ることがあるため余裕を持たせる
-
-execution:
-  max_retry: 10
-  max_steps: 20                 # マルチステップ要求で実行を許すステップ数の上限 (暴走防止)
-  timeout_sec: 30
-  max_output_bytes: 1048576     # stdout/stderr サイズ制限 (1 MiB)
-
-security:
-  allowed_dirs:
-    - .                         # サーバーを起動した場所 (Dir.pwd) を作業ディレクトリとして許可
-  max_file_bytes: 10485760      # ファイルサイズ制限 (10 MiB)
-  allowed_commands:             # run_command で実行を許可するコマンド (whitelist)
-    - git
-    - ruby
-    - node
-    - uv                        # Python 環境構築 (uv init / uv add / venv)
-    - ping                      # ネットワーク疎通確認
-  allow_all_commands: true     # true にすると run_command が allowed_commands を無視し任意コマンドを実行する
-                                 # (⚠️ whitelist を無効化する。信頼できるローカル環境でのみ true にすること)
-
-logging:
-  sqlite_path: ./logs/execution.db
-
-server:
-  host: 127.0.0.1
-  port: 9210
+# chocomint 設定 (DESIGN.md §11)
+llm:
+  base_url: http://localhost:11434/v1
+  model: gemma4:e4b
+  api_key_env: OLLAMA_API_KEY   # 参照する環境変数名 (無ければ空)
+  max_tokens: 4096               # thinking モデルは思考だけで使い切ることがあるため余裕を持たせる
+  timeout_sec: 300               # LLM 応答待ちのタイムアウト (秒)。ローカル LLM は遅いため長めに
+                                 # (ツール実行の execution.timeout_sec とは別物)
+
+verifier:
+  enabled: true
+  # モデルは指定しない。VRAM 節約のため llm.model を共有する (factory.rb 参照)。
+  max_tokens: 1024                # thinking モデルは思考だけで使い切ることがあるため余裕を持たせる
+
+execution:
+  max_retry: 10
+  max_steps: 20                 # マルチステップ要求で実行を許すステップ数の上限 (暴走防止)
+  timeout_sec: 30
+  max_output_bytes: 1048576     # stdout/stderr サイズ制限 (1 MiB)
+
+security:
+  allowed_dirs:
+    - .                         # サーバーを起動した場所 (Dir.pwd) を作業ディレクトリとして許可
+  max_file_bytes: 10485760      # ファイルサイズ制限 (10 MiB)
+  allowed_commands:             # run_command で実行を許可するコマンド (whitelist)
+    - git
+    - ruby
+    - node
+    - uv                        # Python 環境構築 (uv init / uv add / venv)
+    - ping                      # ネットワーク疎通確認
+  allow_all_commands: true     # true にすると run_command が allowed_commands を無視し任意コマンドを実行する
+                                 # (⚠️ whitelist を無効化する。信頼できるローカル環境でのみ true にすること)
+
+logging:
+  sqlite_path: ./logs/execution.db
+
+server:
+  host: 127.0.0.1
+  port: 9210

data/lib/chocomint/config.rb

@@ -1,21 +1,62 @@
 # frozen_string_literal: true
 
 require "yaml"
+require "fileutils"
+require "uri"
 
 module Chocomint
-  # config/config.yml を読み込み、環境変数オーバーライドを適用する。
+  # 設定ファイルを読み込み、環境変数オーバーライドを適用する。
+  #
+  # 設定は XDG Base Directory 準拠のユーザーパス
+  # (~/.config/chocomint/config.yaml。$XDG_CONFIG_HOME があればそちらを優先) に置く。
+  # ユーザー設定がまだ無い場合は、gem 同梱の既定 config をそこへコピーして雛形にする
+  # (初回起動時)。読み込み・保存 (モデル切り替えの persist) はいずれもこのユーザーパスを使う。
   class Config
-    DEFAULT_PATH = File.expand_path("../../config/config.yml", __dir__)
+    # gem 同梱の既定 config (初回のコピー元。読み取り専用として扱う)。
+    BUNDLED_PATH = File.expand_path("../../config/config.yml", __dir__)
 
     attr_reader :data
 
-    def self.load(path = DEFAULT_PATH)
+    # XDG 準拠のユーザー設定ファイルパス (~/.config/chocomint/config.yaml)。
+    def self.user_config_path
+      base = ENV["XDG_CONFIG_HOME"]
+      base = File.join(Dir.home, ".config") if base.nil? || base.empty?
+      File.join(base, "chocomint", "config.yaml")
+    end
+
+    # 設定を読み込む。明示的な path が無ければ user_config_path を使い、そこに
+    # まだファイルが無ければ gem 同梱の既定 config をコピーして作成する。
+    # コピーできない (書き込み不可など) 場合は同梱 config をそのまま読み、
+    # 保存先だけユーザーパスに向ける (persist 時に改めて作成を試みる)。
+    def self.load(path = nil)
+      path ||= ensure_user_config
       raw = File.exist?(path) ? YAML.safe_load(File.read(path)) : {}
-      new(raw || {})
+      new(raw || {}, path)
+    end
+
+    # user_config_path を用意する。無ければ同梱 config をコピーして作る。
+    # 戻り値: 実際に読み込むべきパス (コピー成功時はユーザーパス、失敗時は同梱パス)。
+    def self.ensure_user_config
+      dest = user_config_path
+      return dest if File.exist?(dest)
+
+      begin
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(BUNDLED_PATH, dest) if File.exist?(BUNDLED_PATH)
+        File.exist?(dest) ? dest : BUNDLED_PATH
+      rescue SystemCallError
+        # 書き込み不可などでコピーできないときは同梱 config を読む。
+        BUNDLED_PATH
+      end
     end
 
-    def initialize(data)
+    # 読み込み元パス。llm モデル設定を書き戻す (persist_llm!) のにも使う。
+    # path は第 2 引数 (キーワードにすると Config.new("k" => v) が keyword 誤認で壊れるため)。
+    attr_reader :path
+
+    def initialize(data, path = self.class.user_config_path)
       @data = deep_stringify(data)
+      @path = path
       apply_env_overrides!
     end
 
@@ -37,6 +78,10 @@ module Chocomint
     # マルチステップ実行のステップ数上限。未設定なら max_retry を流用する (暴走防止)。
     def max_steps       = execution.fetch("max_steps", max_retry)
     def timeout_sec     = execution.fetch("timeout_sec", 30)
+    # LLM への HTTP リクエストのタイムアウト (秒)。ツール実行の timeout_sec とは分離する:
+    # ローカル LLM は 1 応答に数分かかることがあり、暴走コマンド用の短い timeout_sec を
+    # 流用すると Net::ReadTimeout で失敗するため。未設定なら余裕を持たせた既定にする。
+    def llm_timeout_sec = llm.fetch("timeout_sec", 300)
     def max_output_bytes = execution.fetch("max_output_bytes", 1_048_576)
 
     def allowed_dirs    = security.fetch("allowed_dirs", ["."])
@@ -49,8 +94,95 @@ module Chocomint
 
     def verifier_enabled? = verifier.fetch("enabled", false)
 
+    # ---- LLM プロバイダ / モデル設定 (AI エディタのモデル切り替え用) ----------
+    #
+    # provider は base_url から推定する: openrouter.ai を含めば "openrouter"、
+    # それ以外 (localhost:11434 等) は "ollama" とみなす。UI での表示・選択に使う。
+    OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+    OLLAMA_BASE_URL     = "http://localhost:11434/v1"
+
+    def llm_base_url = llm.fetch("base_url", OLLAMA_BASE_URL)
+    def llm_model    = llm.fetch("model", nil)
+
+    def llm_provider
+      llm_base_url.to_s.include?("openrouter.ai") ? "openrouter" : "ollama"
+    end
+
+    # Ollama の API ベース URL (末尾に /v1 を含まない)。インストール済みモデル一覧
+    # (/api/tags) の取得に使う。provider が OpenRouter でも Ollama タブのモデルは
+    # ここから取るため、現在の provider に依存させない。
+    #
+    # 優先順位: (1) OLLAMA_HOST 環境変数 (Ollama 標準の設定) →
+    #           (2) 現在の base_url が Ollama を指していればその親 →
+    #           (3) 既定 (http://localhost:11434)。
+    def ollama_api_base
+      if (host = ENV["OLLAMA_HOST"]) && !host.to_s.empty?
+        return normalize_ollama_host(host)
+      end
+      base = llm_provider == "ollama" ? llm_base_url : OLLAMA_BASE_URL
+      base.to_s.sub(%r{/v1/?\z}, "").chomp("/")
+    end
+
+    # 実行時にモデル (と provider) を差し替える。Factory がここを参照して
+    # Planner / chat_client を再構築する。api_key_env は provider ごとに固定する
+    # (Ollama: OLLAMA_API_KEY / OpenRouter: OPENROUTER_API_KEY)。
+    def set_llm!(provider:, model:)
+      llm_cfg = (@data["llm"] ||= {})
+      llm_cfg["model"] = model
+      case provider.to_s
+      when "openrouter"
+        llm_cfg["base_url"] = OPENROUTER_BASE_URL
+        llm_cfg["api_key_env"] = "OPENROUTER_API_KEY"
+      else
+        llm_cfg["base_url"] = OLLAMA_BASE_URL
+        llm_cfg["api_key_env"] = "OLLAMA_API_KEY"
+      end
+      self
+    end
+
+    # 現在の llm 設定 (provider / model / base_url / api_key_env) をユーザー設定へ
+    # 書き戻す。llm セクションだけを更新し、他セクションは元のファイル内容を保つ。
+    #
+    # 保存先は常にユーザーパス (~/.config/chocomint/config.yaml)。読み込み元が
+    # gem 同梱 config だった場合 (初回コピーに失敗したケース) でも、gem ディレクトリ
+    # には書かず、ベースは @path (同梱) の内容を引き継いでユーザーパスへ書き出す。
+    def persist_llm!
+      dest = self.class.user_config_path
+      raw = begin
+        (File.exist?(@path) && YAML.safe_load(File.read(@path))) || {}
+      rescue Psych::SyntaxError
+        {}
+      end
+      raw = deep_stringify(raw)
+      raw["llm"] = @data["llm"]
+      FileUtils.mkdir_p(File.dirname(dest))
+      File.write(dest, YAML.dump(raw))
+      @path = dest
+    end
+
     private
 
+    # Ollama の既定ポート。OLLAMA_HOST にポートが無いとき補う。
+    OLLAMA_DEFAULT_PORT = 11434
+
+    # OLLAMA_HOST の値をクライアントが接続できる URL に正規化する。
+    # OLLAMA_HOST は Ollama サーバーの「待ち受け設定」なので、そのまま接続先には使えない:
+    #   - scheme が無ければ http:// を補う
+    #   - ポートが無ければ既定の 11434 を補う
+    #   - 0.0.0.0 / :: (全 IF で listen する指定) は接続不可なので 127.0.0.1 に読み替える
+    def normalize_ollama_host(host)
+      host = host.to_s.strip
+      host = "http://#{host}" unless host.match?(%r{\Ahttps?://}i)
+      uri = URI.parse(host)
+      uri.host = "127.0.0.1" if ["0.0.0.0", "::", "[::]"].include?(uri.host)
+      # URI::HTTP は scheme 既定ポート (80) を .port に持つため、元文字列に ":ポート" が
+      # 明示されていたかで判定する。無ければ Ollama の既定ポートを補う。
+      uri.port = OLLAMA_DEFAULT_PORT unless host.match?(/:\d+(?:\/|\z)/)
+      uri.to_s.chomp("/")
+    rescue URI::InvalidURIError
+      OLLAMA_BASE_URL.sub(%r{/v1/?\z}, "")
+    end
+
     def apply_env_overrides!
       if (url = ENV["CHOCOMINT_LLM_BASE_URL"])
         (@data["llm"] ||= {})["base_url"] = url

data/lib/chocomint/edit_archive_handlers.rb

@@ -0,0 +1,323 @@
+# frozen_string_literal: true
+
+require "json"
+require "zlib"
+require "stringio"
+require "rubygems/package"
+
+module Chocomint
+  # /edit AI エディタのアーカイブプレビュー用ハンドラ (Server に include して使う)。
+  #
+  # 提供機能:
+  #   GET /edit/archive?path=foo.zip   アーカイブの第一階層エントリ + メタデータ (JSON)
+  #
+  # 対応形式: .zip / .tar / .tar.gz (.tgz) / .gz / .tar.bz2 (.tbz2) / .bz2
+  # いずれも展開はメモリ上で行い、ディスクには書き出さない。tar/zip はエントリを
+  # ストリーム走査し、第一階層 (トップレベル) だけに畳んで返す。
+  #
+  # 対応形式は拡張子でしか判定しない (中身の magic は見ない)。ファイルアクセスは
+  # すべて @path_guard 経由で workspace 内に制限する。
+  module EditArchiveHandlers
+    # 一覧をブラウザで扱える範囲に抑えるためのエントリ数上限 (走査自体の安全弁)。
+    # tar は全走査するため、巨大アーカイブでも到達したら打ち切って capped を立てる。
+    MAX_ARCHIVE_ENTRIES = 20_000
+
+    # bzip2 展開に許す入力サイズ上限 (純Ruby 実装は重いので極端に巨大な .bz2 は弾く)。
+    MAX_BZIP2_INPUT_BYTES = 64 * 1024 * 1024
+
+    def handle_edit_archive(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)
+
+      kind = archive_kind(abs)
+      return edit_json(res, 415, "error" => "unsupported archive format") unless kind
+
+      info = inspect_archive(abs, kind)
+      edit_json(res, 200, { "path" => path }.merge(info))
+    rescue Chocomint::PathAccessError => e
+      edit_json(res, 403, "error" => e.message)
+    rescue ArchiveError => e
+      # 壊れている/未対応の内部構造など。UI 向けにメッセージを返す (500 にはしない)。
+      edit_json(res, 422, "error" => e.message)
+    rescue Chocomint::Error => e
+      edit_json(res, 500, "error" => e.message)
+    end
+
+    # アーカイブ処理中の想定内エラー (壊れたデータ・展開失敗など)。
+    class ArchiveError < StandardError; end
+
+    # ---- 形式判定 -----------------------------------------------------------
+
+    # 拡張子からアーカイブ形式を判定して種別文字列を返す (非対応は nil)。
+    # 種別: "zip" / "tar" / "tar.gz" / "tar.bz2" / "gz" / "bz2"
+    # 二重拡張子 (.tar.gz 等) を単一拡張子 (.gz) より優先する。
+    def archive_kind(abs)
+      lower = File.basename(abs).downcase
+      return "tar.gz" if lower.end_with?(".tar.gz")
+      return "tar.gz" if lower.end_with?(".tgz")
+      return "tar.bz2" if lower.end_with?(".tar.bz2")
+      return "tar.bz2" if lower.end_with?(".tbz2") || lower.end_with?(".tbz")
+      return "zip" if lower.end_with?(".zip")
+      return "tar" if lower.end_with?(".tar")
+      return "gz" if lower.end_with?(".gz")
+      return "bz2" if lower.end_with?(".bz2")
+
+      nil
+    end
+
+    # フロントがメディア/アーカイブを区別できるよう、handle_edit_file からも使う判定。
+    def archive?(abs)
+      !archive_kind(abs).nil?
+    end
+
+    # ---- 検査 (種別ごとにディスパッチ) --------------------------------------
+
+    def inspect_archive(abs, kind)
+      case kind
+      when "zip"                 then inspect_zip(abs)
+      when "tar"                 then inspect_tar(File.binread(abs))
+      when "tar.gz"              then inspect_tar(gunzip(File.binread(abs)))
+      when "tar.bz2"             then inspect_tar(bunzip2(abs))
+      when "gz"                  then inspect_single_compressed(abs, "gzip", strip_ext: ".gz")
+      when "bz2"                 then inspect_single_compressed(abs, "bzip2", strip_ext: ".bz2")
+      else
+        raise ArchiveError, "unsupported archive format"
+      end
+    end
+
+    # ---- tar の走査 ---------------------------------------------------------
+    #
+    # 展開済み tar バイト列を走査し、第一階層に畳んだ entries とメタデータを返す。
+    def inspect_tar(tar_bytes)
+      dirs = {}   # トップレベルのディレクトリ名 => 配下エントリ数
+      files = []  # トップレベルの直下ファイル { name, size }
+      total = 0
+      total_size = 0
+      capped = false
+
+      Gem::Package::TarReader.new(StringIO.new(tar_bytes)) do |reader|
+        reader.each do |entry|
+          name = entry.full_name.to_s
+          next if name.empty? || name == "./"
+
+          total += 1
+          if total > MAX_ARCHIVE_ENTRIES
+            capped = true
+            break
+          end
+
+          rel = normalize_entry_name(name)
+          next if rel.empty?
+
+          size = entry.header.size.to_i
+          total_size += size unless entry.directory?
+          accumulate_top_level(rel, entry.directory?, size, dirs, files)
+        end
+      end
+
+      build_result(dirs, files, total, total_size, capped)
+    rescue Gem::Package::TarInvalidError, Zlib::GzipFile::Error => e
+      raise ArchiveError, "tar を読み取れませんでした: #{e.message}"
+    end
+
+    # ---- zip の走査 (中央ディレクトリを自前パース) --------------------------
+    #
+    # 標準ライブラリだけで済ませるため rubyzip には依存せず、ZIP の End Of Central
+    # Directory (EOCD) → Central Directory を辿ってエントリ名とサイズを読む。
+    # 実データ (ローカルファイルヘッダ) は読まないので大きな zip でも軽い。
+    def inspect_zip(abs)
+      raw = File.binread(abs)
+      cd = zip_central_directory(raw)
+
+      dirs = {}
+      files = []
+      total = 0
+      total_size = 0
+      capped = false
+
+      cd.each do |ent|
+        total += 1
+        if total > MAX_ARCHIVE_ENTRIES
+          capped = true
+          break
+        end
+        rel = normalize_entry_name(ent[:name])
+        next if rel.empty?
+
+        total_size += ent[:size] unless ent[:dir]
+        accumulate_top_level(rel, ent[:dir], ent[:size], dirs, files)
+      end
+
+      build_result(dirs, files, total, total_size, capped)
+    end
+
+    # ZIP の中央ディレクトリを読み、各エントリの { name, size, dir } を返す。
+    def zip_central_directory(raw)
+      eocd = find_eocd(raw)
+      raise ArchiveError, "zip の終端レコードが見つかりません" unless eocd
+
+      count = raw[eocd + 10, 2].unpack1("v")
+      offset = raw[eocd + 16, 4].unpack1("V")
+      entries = []
+      pos = offset
+
+      count.times do
+        break if pos + 46 > raw.bytesize
+        sig = raw[pos, 4]
+        break unless sig == "PK\x01\x02".b # Central Directory File Header
+
+        usize = raw[pos + 24, 4].unpack1("V")          # uncompressed size
+        name_len = raw[pos + 28, 2].unpack1("v")
+        extra_len = raw[pos + 30, 2].unpack1("v")
+        comment_len = raw[pos + 32, 2].unpack1("v")
+        name = raw[pos + 46, name_len].to_s
+        name = zip_decode_name(name)
+        entries << { name: name, size: usize, dir: name.end_with?("/") }
+        pos += 46 + name_len + extra_len + comment_len
+      end
+
+      entries
+    end
+
+    # EOCD (End Of Central Directory, シグネチャ PK\x05\x06) を末尾から探す。
+    # ZIP コメントは最大 65535 バイトなので、末尾 (22 + 65535) だけ後方走査すれば十分。
+    def find_eocd(raw)
+      sig = "PK\x05\x06".b
+      min = [raw.bytesize - (22 + 0xFFFF), 0].max
+      i = raw.bytesize - 22
+      while i >= min
+        return i if raw[i, 4] == sig
+
+        i -= 1
+      end
+      nil
+    end
+
+    # zip のエントリ名を文字列に整える。UTF-8 として妥当ならそれ、駄目なら置換して壊さない。
+    def zip_decode_name(name)
+      s = name.dup.force_encoding("UTF-8")
+      s.valid_encoding? ? s : s.scrub("?")
+    end
+
+    # ---- 単体圧縮ファイル (.gz / .bz2、tar でない) --------------------------
+    #
+    # tar を含まない単なる圧縮ファイルは、展開後の 1 ファイルとして扱う。
+    # 中身の全展開は避け、メタデータ (圧縮/展開サイズ・推定名) だけを返す。
+    def inspect_single_compressed(abs, algorithm, strip_ext:)
+      compressed_size = File.size(abs)
+      inner_name = File.basename(abs)
+      inner_name = inner_name[0...-strip_ext.length] if inner_name.downcase.end_with?(strip_ext)
+
+      uncompressed_size =
+        case algorithm
+        when "gzip"  then gzip_uncompressed_size(abs)
+        when "bzip2" then bunzip2(abs).bytesize
+        end
+
+      {
+        "archive" => algorithm == "gzip" ? "gz" : "bz2",
+        "single" => true,
+        "entries" => [{ "name" => inner_name, "dir" => false, "size" => uncompressed_size }],
+        "total_entries" => 1,
+        "total_size" => uncompressed_size,
+        "compressed_size" => compressed_size,
+        "capped" => false
+      }
+    end
+
+    # ---- 展開ヘルパ ---------------------------------------------------------
+
+    def gunzip(bytes)
+      Zlib::GzipReader.new(StringIO.new(bytes)).read
+    rescue Zlib::GzipFile::Error => e
+      raise ArchiveError, "gzip を展開できませんでした: #{e.message}"
+    end
+
+    # gzip 末尾 4 バイトの ISIZE (展開後サイズ mod 2^32)。4GB 未満の実用ケース向け。
+    def gzip_uncompressed_size(abs)
+      tail = File.open(abs, "rb") { |f| f.seek(-4, IO::SEEK_END); f.read(4) }
+      tail ? tail.unpack1("V") : nil
+    rescue SystemCallError
+      nil
+    end
+
+    # bzip2 を純Ruby (rbzip2) で展開する。ネイティブ libbz2 は不要。
+    def bunzip2(abs)
+      require "rbzip2"
+      raw = File.binread(abs)
+      if raw.bytesize > MAX_BZIP2_INPUT_BYTES
+        raise ArchiveError, "bzip2 ファイルが大きすぎます (上限 #{MAX_BZIP2_INPUT_BYTES / (1024 * 1024)}MB)"
+      end
+
+      RBzip2.default_adapter::Decompressor.new(StringIO.new(raw)).read
+    rescue LoadError
+      raise ArchiveError, "bzip2 の展開には rbzip2 gem が必要です"
+    rescue ArchiveError
+      raise
+    rescue StandardError => e
+      raise ArchiveError, "bzip2 を展開できませんでした: #{e.message}"
+    end
+
+    # ---- 集計の共通処理 -----------------------------------------------------
+
+    # エントリ名を正規化する ("./" 前置や重複スラッシュを除く。先頭は相対に統一)。
+    def normalize_entry_name(name)
+      s = name.tr("\\", "/")
+      s = s.sub(%r{\A\./}, "")
+      s = s.sub(%r{\A/+}, "")
+      s.gsub(%r{/+}, "/")
+    end
+
+    # 正規化済みエントリを「第一階層」に畳んで dirs / files に足し込む。
+    #   "src/main.rb" → トップレベル dir "src" を登録し配下件数 +1
+    #   "README.md"   → トップレベル直下 file "README.md"
+    #   "src/"        → dir "src" を登録するだけ (ディレクトリ自身なので件数は増やさない)
+    #   "emptydir/"   → dir "emptydir" を件数 0 で登録 (空ディレクトリ)
+    def accumulate_top_level(rel, is_dir, size, dirs, files)
+      # 末尾スラッシュはディレクトリ自身のエントリ。区切りとしての "/" と区別する。
+      trailing_dir = rel.end_with?("/")
+      trimmed = trailing_dir ? rel.chomp("/") : rel
+      slash = trimmed.index("/")
+
+      if slash.nil?
+        # トップレベル直下のエントリ (ファイル or ディレクトリ自身)。
+        if is_dir || trailing_dir
+          dirs[trimmed] ||= 0 # 件数は増やさない (自身の登録だけ)。
+        else
+          files << { name: trimmed, size: size }
+        end
+      else
+        # 配下エントリ → トップレベルのディレクトリに畳んで件数を +1。
+        top = trimmed[0...slash]
+        dirs[top] ||= 0
+        dirs[top] += 1
+      end
+    end
+
+    # dirs / files から JSON 用の結果ハッシュを組み立てる。
+    # entries はディレクトリ→ファイルの順、各名前順 (一覧の並びに揃える)。
+    def build_result(dirs, files, total, total_size, capped)
+      dir_entries = dirs.keys.sort.map do |name|
+        { "name" => name, "dir" => true, "child_count" => dirs[name] }
+      end
+      # 同名ファイルの重複は稀だが、名前順で安定させる。
+      file_entries = files.uniq { |f| f[:name] }
+                          .sort_by { |f| f[:name] }
+                          .map { |f| { "name" => f[:name], "dir" => false, "size" => f[:size] } }
+
+      {
+        "archive" => "tar_or_zip",
+        "single" => false,
+        "entries" => dir_entries + file_entries,
+        "total_entries" => total,
+        "total_size" => total_size,
+        "capped" => capped
+      }
+    end
+  end
+end