svg_icon 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11778daaa40d8cb36e0a8637b59b96fbbe5e6b266bef88aa7d5aa5b5937df6c1
-  data.tar.gz: f939de88a632a7d8767f11ae14dde71c12d8eb59c026f7dc615b0248e7d47cbd
+  metadata.gz: b388bb80ccfff538510163078ff382d07908549abaa76da0382af3ee7bc1ed07
+  data.tar.gz: b646054bc7c5035c49f51dd4e6845154aba0390d0d37d5804462e0869ef74ebf
 SHA512:
-  metadata.gz: 5a115c8d3f6b37e3c21fdbb5f43dc003eeb085d4e3f578b155bc592d98d24208abcee66e14e10b7842aa7223fbe9ddec7594463765033b382285b5c15f3f4577
-  data.tar.gz: '090f3b45bf7250d42ec97527027420ed04c9a2baf5077c33b72e3ee9d3de22d55281a6d8dd89c83a9e864d68fd3193fa1342c4ac0d5fbd4f2790d701c9847b27'
+  metadata.gz: 88cad87bd6dbad2faf9ac6458f9f0b30cb0e851df11eaac75034b0b85bd068a0cd820b4ea41d860f012ea697d923f3c6f10fdf44d6df5274cea4adaff46c5686
+  data.tar.gz: 527479eb7d5a90b3a10d4473298db0d166acefac938d4f227c40fc76e49872be8980f44f7c24cff4f9cc0017cc1fc67c53c149e574afcc84575dc3358cb0b4c1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    svg_icon (0.1.0)
+    svg_icon (0.4.0)
       activesupport (>= 5.0)
       multi_json
 

data/README.md

@@ -22,11 +22,10 @@ Or install it yourself as:
 
 Add `svg_icon.rb` in initializers folder
 
-```
-# frozen_string_literal: true
-
+```ruby
 SvgIcon.configure do |config|
-  # config.icon = "bi" # Options are "bi" and "bx"
+  # config.icon = "lucide" # icon set name: "lucide", "bi", "bx", "heroicons", or any fetched set
+  config.icons_path = Rails.root.join("config", "svg_icons") # defaults to "config/svg_icons" under the project root
 
   ##
   # You can set a default class for icon
@@ -40,6 +39,19 @@ add ` include SvgIcon::Helper` to `ApplicationHelper`
 <%= svg_icon("search") %>
 ```
 
+## Fetching icon sets
+
+The gem bundles a few icon sets (lucide, bi, bx, heroicons). To use any other
+[iconify icon set](https://github.com/iconify/icon-sets/tree/master/json), download it into your project:
+
+    $ svg_icon fetch bi
+
+This downloads `bi.json` into `config/svg_icons/`. Set `config.icon = "bi"` to use it —
+the gem looks for `<icon>.json` in `config/svg_icons/` first, then falls back to bundled data.
+
+Commit `config/svg_icons/` to your repository so deploys don't need to re-fetch.
+Re-run `svg_icon fetch <name>` to update an existing set.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/docs/superpowers/plans/2026-08-18-svg-icon-fetch-cli.md

@@ -0,0 +1,557 @@
+# svg_icon fetch CLI Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a `svg_icon fetch <name>` CLI that downloads icon sets from iconify/icon-sets into the project, usable as independent icon sets via config.
+
+**Architecture:** New `SvgIcon::Fetcher` class (net/http, injectable for tests) handles download/validate/atomic-write. New `SvgIcon::CLI` class + `exe/svg_icon` thin wrapper dispatch `fetch`. Configuration gains `icons_path`; `file_data` resolution order becomes external `icons_path/<icon>.json` → bundled `lib/data/<icon>.json` → raise.
+
+**Tech Stack:** Ruby, minitest, net/http (stdlib), multi_json, OptionParser-free manual dispatch (tiny surface).
+
+**Spec:** `docs/superpowers/specs/2026-08-18-svg-icon-fetch-design.md`
+
+---
+
+### Task 1: `icons_path` config + external-first data resolution
+
+**Files:**
+- Modify: `lib/svg_icon/configuration.rb`
+- Modify: `lib/svg_icon.rb`
+- Test: `test/svg_icon_test.rb`
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `test/svg_icon_test.rb`:
+
+```ruby
+def test_default_icons_path_points_to_project_config_dir
+  assert_equal File.join(Dir.pwd, "config", "svg_icons"), SvgIcon.configuration.icons_path
+end
+
+def test_icons_loads_from_icons_path_when_present
+  Dir.mktmpdir do |dir|
+    File.write(File.join(dir, "custom.json"), %({"prefix":"custom","icons":{"x":{"body":"1"}}}))
+    SvgIcon.configure { |config| config.icon = "custom"; config.icons_path = dir }
+    assert_equal "custom", SvgIcon.icons["prefix"]
+  end
+end
+
+def test_icons_falls_back_to_bundled_data
+  Dir.mktmpdir do |dir|
+    SvgIcon.configure { |config| config.icon = "lucide"; config.icons_path = dir }
+    assert_equal "lucide", SvgIcon.icons["prefix"]
+  end
+end
+
+def test_icons_raises_when_file_missing_everywhere
+  Dir.mktmpdir do |dir|
+    SvgIcon.configure { |config| config.icon = "nonexistent"; config.icons_path = dir }
+    error = assert_raises(SvgIcon::Error) { SvgIcon.icons }
+    assert_match(/Icon data file not found/, error.message)
+  end
+end
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `bundle exec ruby -Ilib -Itest test/svg_icon_test.rb`
+Expected: `test_default_icons_path...` FAILS with `NoMethodError: undefined method 'icons_path'`; the other three fail with `Icon data file not found: .../lib/data/custom.json` (external dir never consulted).
+
+- [ ] **Step 3: Add `icons_path` to Configuration**
+
+In `lib/svg_icon/configuration.rb`, change the class to:
+
+```ruby
+class Configuration
+  DEFAULT_ICON = "lucide"
+
+  attr_accessor :icon
+  attr_accessor :default_class
+  attr_accessor :extra_icons_path
+  attr_accessor :icons_path
+
+  def initialize
+    @icon = DEFAULT_ICON
+    @icons_path = File.join(Dir.pwd, "config", "svg_icons")
+  end
+end
+```
+
+- [ ] **Step 4: External-first resolution in `lib/svg_icon.rb`**
+
+Replace the `data_path` and `file_data` methods (currently `data_path` builds `File.join(__dir__, "data", ...)` and `file_data` memoizes by path) with:
+
+```ruby
+def file_data
+  @file_data ||= {}
+  @file_data[icon] ||= begin
+    path = resolve_icon_path
+    raise Error, "Icon data file not found: #{path}" unless File.exist?(path)
+
+    File.read(path)
+  end
+end
+
+def resolve_icon_path
+  external = File.join(configuration.icons_path, "#{icon}.json")
+  return external if File.exist?(external)
+
+  File.join(__dir__, "data", "#{icon}.json")
+end
+```
+
+Then in `merge_extra_icons` (same file), replace `#{data_path}` with `#{resolve_icon_path}` in the error message. Delete the now-unused `data_path` method.
+
+- [ ] **Step 5: Run full test suite**
+
+Run: `bundle exec rake test`
+Expected: all 26 tests pass (22 existing + 4 new).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add lib/svg_icon.rb lib/svg_icon/configuration.rb test/svg_icon_test.rb
+git commit -m "feat: support external icon sets via icons_path config"
+```
+
+---
+
+### Task 2: `SvgIcon::Fetcher`
+
+**Files:**
+- Create: `lib/svg_icon/fetcher.rb`
+- Create: `test/fetcher_test.rb`
+- Modify: `lib/svg_icon.rb` (require fetcher)
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `test/fetcher_test.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require "test_helper"
+require "tmpdir"
+
+class FetcherTest < Minitest::Test
+  FakeResponse = Struct.new(:code, :body)
+
+  class FakeHttp
+    attr_reader :requests
+
+    def initialize(code, body)
+      @code = code
+      @body = body
+      @requests = []
+    end
+
+    def get_response(uri)
+      @requests << uri
+      FakeResponse.new(@code, @body)
+    end
+  end
+
+  def setup
+    @dir = Dir.mktmpdir
+  end
+
+  def teardown
+    FileUtils.remove_entry(@dir)
+  end
+
+  def test_fetch_downloads_and_writes_file
+    body = %({"prefix":"bi","icons":{"search":{"body":"<path/>"}}})
+    http = FakeHttp.new("200", body)
+    fetcher = SvgIcon::Fetcher.new(http: http)
+    destination = File.join(@dir, "bi.json")
+
+    assert fetcher.fetch("bi", destination)
+    assert_equal body, File.read(destination)
+    assert_equal "https://raw.githubusercontent.com/iconify/icon-sets/master/json/bi.json", http.requests.first.to_s
+  end
+
+  def test_fetch_creates_destination_directory
+    http = FakeHttp.new("200", %({"icons":{"x":{"body":"1"}}}))
+    destination = File.join(@dir, "nested", "bi.json")
+
+    SvgIcon::Fetcher.new(http: http).fetch("bi", destination)
+
+    assert_equal %({"icons":{"x":{"body":"1"}}}), File.read(destination)
+  end
+
+  def test_fetch_uses_custom_base_url
+    http = FakeHttp.new("200", %({"icons":{"x":{"body":"1"}}}))
+    SvgIcon::Fetcher.new(base_url: "https://example.com/sets", http: http).fetch("bi", File.join(@dir, "out.json"))
+
+    assert_equal "https://example.com/sets/bi.json", http.requests.first.to_s
+  end
+
+  def test_fetch_raises_on_http_error
+    http = FakeHttp.new("404", "Not Found")
+    error = assert_raises(SvgIcon::FetchError) do
+      SvgIcon::Fetcher.new(http: http).fetch("bi", File.join(@dir, "bi.json"))
+    end
+    assert_match(/HTTP 404/, error.message)
+    assert_match(/not found/, error.message)
+  end
+
+  def test_fetch_raises_on_invalid_json
+    http = FakeHttp.new("200", "not-json")
+    error = assert_raises(SvgIcon::FetchError) do
+      SvgIcon::Fetcher.new(http: http).fetch("bi", File.join(@dir, "bi.json"))
+    end
+    assert_match(/invalid JSON/, error.message)
+  end
+
+  def test_fetch_raises_when_icons_key_missing
+    http = FakeHttp.new("200", %({"prefix":"bi"}))
+    error = assert_raises(SvgIcon::FetchError) do
+      SvgIcon::Fetcher.new(http: http).fetch("bi", File.join(@dir, "bi.json"))
+    end
+    assert_match(/must contain an 'icons' object/, error.message)
+  end
+
+  def test_failed_fetch_leaves_no_files
+    http = FakeHttp.new("404", "Not Found")
+    destination = File.join(@dir, "bi.json")
+
+    assert_raises(SvgIcon::FetchError) { SvgIcon::Fetcher.new(http: http).fetch("bi", destination) }
+
+    refute File.exist?(destination)
+    assert_empty Dir.glob(File.join(@dir, "*.tmp*"))
+  end
+end
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `bundle exec ruby -Ilib -Itest test/fetcher_test.rb`
+Expected: all FAIL with `NameError: uninitialized constant SvgIcon::Fetcher`.
+
+- [ ] **Step 3: Implement Fetcher**
+
+Create `lib/svg_icon/fetcher.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require "net/http"
+require "tempfile"
+
+module SvgIcon
+  class FetchError < Error; end
+
+  class Fetcher
+    DEFAULT_BASE_URL = "https://raw.githubusercontent.com/iconify/icon-sets/master/json"
+
+    def initialize(base_url: DEFAULT_BASE_URL, http: Net::HTTP)
+      @base_url = base_url
+      @http = http
+    end
+
+    def fetch(name, destination)
+      response = @http.get_response(uri_for(name))
+      raise FetchError, "Failed to fetch #{name}: HTTP #{response.code}#{not_found_hint(response.code)}" unless response.code == "200"
+
+      parse(response.body, name)
+      write(response.body, destination)
+      true
+    end
+
+    private
+
+    def uri_for(name)
+      URI.join("#{@base_url}/", "#{name}.json")
+    end
+
+    def not_found_hint(code)
+      code == "404" ? " (icon set not found)" : ""
+    end
+
+    def parse(body, name)
+      data = MultiJson.load(body)
+      return if data.is_a?(Hash) && data["icons"].is_a?(Hash)
+
+      raise FetchError, "Invalid icon set '#{name}': JSON must contain an 'icons' object"
+    rescue MultiJson::ParseError => e
+      raise FetchError, "Invalid icon set '#{name}': invalid JSON (#{e.message})"
+    end
+
+    def write(body, destination)
+      dir = File.dirname(destination)
+      FileUtils.mkdir_p(dir)
+      temp = Tempfile.new([".#{File.basename(destination)}", ".tmp"], dir)
+      begin
+        temp.write(body)
+        temp.flush
+        File.rename(temp.path, destination)
+      ensure
+        temp.close!
+      end
+    end
+  end
+end
+```
+
+In `lib/svg_icon.rb`, add `require_relative "svg_icon/fetcher"` after the `require_relative "svg_icon/helper"` line.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `bundle exec ruby -Ilib -Itest test/fetcher_test.rb`
+Expected: all 7 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/svg_icon.rb lib/svg_icon/fetcher.rb test/fetcher_test.rb
+git commit -m "feat: add Fetcher to download icon sets"
+```
+
+---
+
+### Task 3: `SvgIcon::CLI` + `exe/svg_icon`
+
+**Files:**
+- Create: `lib/svg_icon/cli.rb`
+- Create: `exe/svg_icon`
+- Create: `test/cli_test.rb`
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `test/cli_test.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require "test_helper"
+
+class CliTest < Minitest::Test
+  FakeFetcher = Struct.new(:name, :destination) do
+    def fetch(name, destination)
+      self.name = name
+      self.destination = destination
+    end
+  end
+
+  def test_fetch_downloads_into_icons_path
+    fake = FakeFetcher.new
+    SvgIcon::Fetcher.stub(:new, fake) do
+      out, = capture_io { SvgIcon::CLI.run(["fetch", "bi"]) }
+      assert_equal "bi", fake.name
+      assert_equal File.join(SvgIcon.configuration.icons_path, "bi.json"), fake.destination
+      assert_includes out, "Saved to"
+    end
+  end
+
+  def test_fetch_without_name_exits_with_usage
+    error = assert_raises(SystemExit) do
+      capture_io { SvgIcon::CLI.run(["fetch"]) }
+    end
+    assert_equal 1, error.status
+  end
+
+  def test_fetch_with_invalid_name_exits
+    error = assert_raises(SystemExit) do
+      capture_io { SvgIcon::CLI.run(["fetch", "../evil"]) }
+    end
+    assert_equal 1, error.status
+  end
+
+  def test_fetch_with_extra_arguments_exits
+    error = assert_raises(SystemExit) do
+      capture_io { SvgIcon::CLI.run(["fetch", "bi", "extra"]) }
+    end
+    assert_equal 1, error.status
+  end
+
+  def test_fetch_propagates_fetch_error
+    SvgIcon::Fetcher.stub(:new, proc { |_base_url, _http| raise SvgIcon::FetchError, "boom" }) do
+      _, err = capture_io do
+        error = assert_raises(SystemExit) { SvgIcon::CLI.run(["fetch", "bi"]) }
+        assert_equal 1, error.status
+      end
+      assert_includes err, "boom"
+    end
+  end
+
+  def test_unknown_command_exits
+    error = assert_raises(SystemExit) do
+      capture_io { SvgIcon::CLI.run(["frobnicate"]) }
+    end
+    assert_equal 1, error.status
+  end
+
+  def test_help_prints_usage_without_error
+    out, = capture_io { SvgIcon::CLI.run(["help"]) }
+    assert_includes out, "Usage:"
+  end
+end
+```
+
+Note: `SvgIcon::Fetcher.stub(:new, fake)` stubs `SvgIcon::Fetcher.new`; the CLI must call `SvgIcon::Fetcher.new` (with default args) so the stub intercepts it. The `proc` stub in `test_fetch_propagates_fetch_error` works because minitest calls the stub object's `call` when the stubbed method is invoked with matching args — the proc receives the same args `new` was called with.
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `bundle exec ruby -Ilib -Itest test/cli_test.rb`
+Expected: FAIL with `NameError: uninitialized constant SvgIcon::CLI`.
+
+- [ ] **Step 3: Implement CLI**
+
+Create `lib/svg_icon/cli.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+module SvgIcon
+  class CLI
+    def self.run(argv)
+      new(argv).run
+    end
+
+    def initialize(argv)
+      @argv = argv
+    end
+
+    def run
+      command = @argv.shift
+      case command
+      when "fetch"
+        fetch
+      when nil, "help", "--help", "-h"
+        puts usage
+      else
+        warn "Unknown command: #{command}"
+        warn usage
+        exit 1
+      end
+    end
+
+    private
+
+    def fetch
+      name = @argv.shift
+      unless valid_name?(name) && @argv.empty?
+        warn "Usage: svg_icon fetch <icon_set_name>"
+        exit 1
+      end
+
+      destination = File.join(SvgIcon.configuration.icons_path, "#{name}.json")
+      puts "Fetching #{name} from iconify/icon-sets"
+      SvgIcon::Fetcher.new.fetch(name, destination)
+      puts "Saved to #{relative_path(destination)}"
+    rescue SvgIcon::FetchError => e
+      warn e.message
+      exit 1
+    rescue StandardError => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    def valid_name?(name)
+      !name.nil? && !name.empty? && name.match?(/\A[a-z0-9\-_]+\z/)
+    end
+
+    def relative_path(path)
+      path.sub("#{Dir.pwd}/", "")
+    end
+
+    def usage
+      <<~TEXT
+        Usage: svg_icon COMMAND
+
+        Commands:
+          fetch NAME    Download icon set NAME (e.g. bi) from iconify/icon-sets into #{SvgIcon.configuration.icons_path}
+          help          Show this help
+      TEXT
+    end
+  end
+end
+```
+
+Create `exe/svg_icon` (make executable):
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "svg_icon"
+require "svg_icon/cli"
+
+exit(SvgIcon::CLI.run(ARGV) || 0)
+```
+
+In `lib/svg_icon.rb`, add `require_relative "svg_icon/cli"` after `require_relative "svg_icon/fetcher"`.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `bundle exec ruby -Ilib -Itest test/cli_test.rb`
+Expected: all 7 tests PASS.
+
+- [ ] **Step 5: Verify the executable works end-to-end**
+
+Run: `chmod +x exe/svg_icon && bundle exec ruby exe/svg_icon fetch nonexistent-set-xyz && echo "UNEXPECTED SUCCESS" || echo "expected failure"`
+Expected: `expected failure` (network 404 or resolve failure → non-zero exit). Then run `bundle exec ruby exe/svg_icon help` — expect usage text.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add lib/svg_icon.rb lib/svg_icon/cli.rb exe/svg_icon test/cli_test.rb
+git commit -m "feat: add svg_icon fetch CLI"
+```
+
+---
+
+### Task 4: README + full verification
+
+**Files:**
+- Modify: `README.md`
+- Test: all existing tests
+
+- [ ] **Step 1: Update README**
+
+Replace the `## Usage` section's initializer example block (the `SvgIcon.configure` code block) with:
+
+```ruby
+SvgIcon.configure do |config|
+  # config.icon = "lucide" # icon set name: "lucide", "bi", "bx", "heroicons", or any fetched set
+  config.icons_path = Rails.root.join("config", "svg_icons") # defaults to "config/svg_icons" under the project root
+
+  ##
+  # You can set a default class for icon
+  config.default_class = ""
+end
+```
+
+After the `<%= svg_icon("search") %>` usage example, add:
+
+```markdown
+## Fetching icon sets
+
+The gem bundles a few icon sets (lucide, bi, bx, heroicons). To use any other
+[iconify icon set](https://github.com/iconify/icon-sets/tree/master/json), download it into your project:
+
+    $ svg_icon fetch bi
+
+This downloads `bi.json` into `config/svg_icons/`. Set `config.icon = "bi"` to use it —
+the gem looks for `<icon>.json` in `config/svg_icons/` first, then falls back to bundled data.
+
+Commit `config/svg_icons/` to your repository so deploys don't need to re-fetch.
+Re-run `svg_icon fetch <name>` to update an existing set.
+```
+
+- [ ] **Step 2: Run full test suite**
+
+Run: `bundle exec rake test`
+Expected: 40 runs, 0 failures, 0 errors (22 existing + 4 + 7 + 7 new).
+
+- [ ] **Step 3: Verify gem packaging includes the executable**
+
+Run: `gem build svg_icon.gemspec && tar -tf svg_icon-*.gem > /dev/null; rm svg_icon-*.gem`
+Expected: build succeeds. The new `exe/svg_icon` is tracked by git (committed in Task 3), so `git ls-files` includes it and the gem ships it.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: document svg_icon fetch CLI"
+```

data/docs/superpowers/specs/2026-08-18-svg-icon-fetch-design.md

@@ -0,0 +1,100 @@
+# svg_icon fetch CLI — 设计文档
+
+- 日期:2026-08-18
+- 状态:已批准
+
+## 背景
+
+gem 内置的 icon set json(bi/bx/lucide/heroicons)来自 [iconify/icon-sets](https://github.com/iconify/icon-sets/tree/master/json)。把所有 icon set 打包进 gem 不现实。需要一个 CLI 命令,让用户从 iconify/icon-sets 抓取任意 icon set 到项目本地,并通过配置使用。
+
+## 目标
+
+- `svg_icon fetch <name>` 从 iconify/icon-sets 下载 `<name>.json` 到项目 `config/svg_icons/` 目录
+- 下载的 json 作为独立 icon set 使用:`config.icon = "<name>"` 时优先加载它,与内置 lucide 等平级
+- 零新增运行时依赖(标准库 `net/http` + 现有 `multi_json`)
+- 下载后离线可用,建议提交进版本控制
+
+## 架构
+
+### 1. CLI(`exe/svg_icon`)
+
+```
+$ svg_icon fetch bi
+Fetching https://raw.githubusercontent.com/iconify/icon-sets/master/json/bi.json
+Saved to config/svg_icons/bi.json
+```
+
+- 使用 `OptionParser` 做子命令分发
+- `fetch <name>` 行为:
+  - 下载 URL:`https://raw.githubusercontent.com/iconify/icon-sets/master/json/<name>.json`
+  - 目标:`<icons_path>/<name>.json`,目录不存在时自动创建
+  - 先写临时文件,校验成功后 rename 到目标;失败不留下半截文件
+  - 目标已存在则覆盖(作为更新手段)
+  - 校验规则:JSON 可解析,且是 Hash 且含 `icons`(Hash)键
+- 错误处理(全部 stderr + exit 1):
+  - 网络错误 / HTTP 非 200 → `FetchError`
+  - JSON 无效或不含 `icons` → `FetchError`
+  - 缺少子命令或参数 → usage 提示,exit 1
+
+### 2. 配置扩展(`lib/svg_icon/configuration.rb`)
+
+- 新增 `attr_accessor :icons_path`,默认 `File.join(Dir.pwd, "config/svg_icons")`
+- 语义:外部 icon set 的查找目录
+
+### 3. 数据查找(`lib/svg_icon.rb`)
+
+`file_data` 查找顺序:
+
+1. 外部 `<icons_path>/<icon>.json`(存在则优先)
+2. 内置 `lib/data/<icon>.json`
+3. 都不存在 → 现有 `SvgIcon::Error`("Icon data file not found")
+
+外部优先:用户下载的版本覆盖内置,且内置 bi/bx 等与下载同名时以外部为准(数据更新)。
+
+### 4. Fetcher(`lib/svg_icon/fetcher.rb`)
+
+```ruby
+module SvgIcon
+  class FetchError < Error; end
+
+  class Fetcher
+    def initialize(base_url: DEFAULT_BASE_URL, http: Net::HTTP, ...)
+    def fetch(name, destination) # destination 是完整目标文件路径(含文件名),由调用方组装
+    # 返回 bool/抛出 FetchError
+  end
+end
+```
+
+- `base_url` 和 http 客户端可注入,便于测试
+- 下载 → 解析校验 → 写临时文件 → rename
+
+## 错误处理汇总
+
+| 场景 | 行为 |
+| --- | --- |
+| 网络错误 / DNS 失败 | `SvgIcon::FetchError`,exit 1 |
+| HTTP 404(icon set 不存在) | `SvgIcon::FetchError`,exit 1 |
+| 返回体不是合法 JSON | `SvgIcon::FetchError`,exit 1 |
+| JSON 不含 `icons` 对象 | `SvgIcon::FetchError`,exit 1 |
+| `icons_path` 目录不可写 | 原样异常,exit 1 |
+
+## 测试(minitest)
+
+- **fetcher_test.rb**(`test/fetcher_test.rb`)
+  - 成功下载并写入正确文件(mock HTTP)
+  - 404 → FetchError
+  - 无效 JSON → FetchError
+  - 缺 `icons` 键 → FetchError
+  - 失败时不留下临时/半截文件
+- **查找顺序**(`test/svg_icon_test.rb` 扩展)
+  - `icons_path` 存在同名文件 → 加载外部
+  - 外部没有 → 回退内置
+  - 都没有 → `SvgIcon::Error`
+- **CLI 集成**(`test/cli_test.rb`)
+  - 在临时目录跑 `svg_icon fetch <name>`,断言 exit 0、文件写入
+  - 无效参数 → exit 1
+
+## README 更新
+
+- 新增 "Fetching icon sets" 章节:安装、`svg_icon fetch bi` 用法、`config.icon` / `config.icons_path` 示例
+- 建议把 `config/svg_icons/` 提交进版本控制,部署无需重新抓取

data/exe/svg_icon

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "svg_icon"
+require "svg_icon/cli"
+
+exit(SvgIcon::CLI.run(ARGV) || 0)

data/lib/svg_icon/cli.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "fetcher"
+
+module SvgIcon
+  class CLI
+    def self.run(argv)
+      new(argv).run
+    end
+
+    def initialize(argv)
+      @argv = argv
+    end
+
+    def run
+      command = @argv.shift
+      case command
+      when "fetch"
+        fetch
+      when nil, "help", "--help", "-h"
+        puts usage
+      else
+        warn "Unknown command: #{command}"
+        warn usage
+        exit 1
+      end
+    end
+
+    private
+
+    def fetch
+      name = @argv.shift
+      unless valid_name?(name) && @argv.empty?
+        warn "Usage: svg_icon fetch <icon_set_name>"
+        exit 1
+      end
+
+      destination = File.join(SvgIcon.configuration.icons_path, "#{name}.json")
+      puts "Fetching #{name} from iconify/icon-sets"
+      SvgIcon::Fetcher.new.fetch(name, destination)
+      puts "Saved to #{relative_path(destination)}"
+    rescue SvgIcon::FetchError => e
+      warn e.message
+      exit 1
+    rescue StandardError => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    def valid_name?(name)
+      !name.nil? && name =~ SvgIcon::Fetcher::NAME_PATTERN
+    end
+
+    def relative_path(path)
+      path.sub("#{Dir.pwd}/", "")
+    end
+
+    def usage
+      <<~TEXT
+        Usage: svg_icon COMMAND
+
+        Commands:
+          fetch NAME    Download icon set NAME (e.g. bi) from iconify/icon-sets into #{SvgIcon.configuration.icons_path}
+          help          Show this help
+      TEXT
+    end
+  end
+end

data/lib/svg_icon/configuration.rb

@@ -7,9 +7,11 @@ module SvgIcon
     attr_accessor :icon
     attr_accessor :default_class
     attr_accessor :extra_icons_path
+    attr_accessor :icons_path
 
     def initialize
       @icon = DEFAULT_ICON
+      @icons_path = File.join(Dir.pwd, "config", "svg_icons")
     end
   end
 

data/lib/svg_icon/fetcher.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "net/http"
+require "openssl"
+require "tempfile"
+require "uri"
+
+module SvgIcon
+  class FetchError < Error; end
+
+  class Fetcher
+    DEFAULT_BASE_URL = "https://raw.githubusercontent.com/iconify/icon-sets/master/json"
+    NAME_PATTERN = /\A[a-z0-9\-_]+\z/
+
+    def initialize(base_url: DEFAULT_BASE_URL, http: Net::HTTP)
+      @base_url = base_url
+      @http = http
+    end
+
+    def fetch(name, destination)
+      validate_name!(name)
+      response = fetch_response(name)
+      raise FetchError, "Failed to fetch #{name}: HTTP #{response.code}#{not_found_hint(response.code)}" unless response.code == "200"
+
+      parse(response.body, name)
+      write(response.body, destination)
+      true
+    end
+
+    private
+
+    def validate_name!(name)
+      raise FetchError, "Invalid icon set name: #{name}" unless name.is_a?(String) && name =~ NAME_PATTERN
+    end
+
+    def fetch_response(name)
+      @http.get_response(uri_for(name))
+    rescue SocketError, SystemCallError, Timeout::Error, EOFError, IOError, OpenSSL::SSL::SSLError => e
+      raise FetchError, "Failed to fetch #{name}: #{e.message}"
+    end
+
+    def uri_for(name)
+      URI.join("#{@base_url}/", "#{name}.json")
+    end
+
+    def not_found_hint(code)
+      code == "404" ? " (icon set not found)" : ""
+    end
+
+    def parse(body, name)
+      data = MultiJson.load(body)
+      return if data.is_a?(Hash) && data["icons"].is_a?(Hash)
+
+      raise FetchError, "Invalid icon set '#{name}': JSON must contain an 'icons' object"
+    rescue MultiJson::ParseError => e
+      raise FetchError, "Invalid icon set '#{name}': invalid JSON (#{e.message})"
+    end
+
+    def write(body, destination)
+      dir = File.dirname(destination)
+      FileUtils.mkdir_p(dir)
+      temp = Tempfile.new([".#{File.basename(destination)}", ".tmp"], dir)
+      begin
+        temp.write(body)
+        temp.flush
+        File.rename(temp.path, destination)
+      ensure
+        temp.close!
+      end
+    end
+  end
+end

data/lib/svg_icon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SvgIcon
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/svg_icon.rb

@@ -11,11 +11,14 @@ require "active_support/core_ext/string/output_safety"
 module SvgIcon
   class Error < StandardError; end
 
+  require_relative "svg_icon/fetcher"
+  require_relative "svg_icon/cli"
+
   extend self
 
   def icons
     @icons ||= {}
-    @icons[icon] ||= MultiJson.load(file_data)
+    @icons[file_cache_key_for(resolve_icon_path)] ||= MultiJson.load(file_data)
   end
 
   def icons_json
@@ -41,25 +44,34 @@ module SvgIcon
     SvgIcon.configuration
   end
 
-  def data_path
-    File.join(__dir__, "data", "#{icon}.json")
-  end
-
   def file_data
     @file_data ||= {}
-    @file_data[data_path] ||= begin
-      path = data_path
-      raise Error, "Icon data file not found: #{path}" unless File.exist?(path)
+    @file_data[file_cache_key_for(resolve_icon_path)] ||= begin
+      path = resolve_icon_path
+      raise Error, "Icon data file not found: #{icon} (looked in #{configuration.icons_path} and bundled data)" unless File.exist?(path)
 
       File.read(path)
     end
   end
 
+  def resolve_icon_path
+    external = File.join(configuration.icons_path, "#{icon}.json")
+    return external if File.exist?(external)
+
+    File.join(__dir__, "data", "#{icon}.json")
+  end
+
+  def file_cache_key_for(path)
+    return nil unless path
+
+    "#{path}:#{File.exist?(path) ? File.mtime(path).to_i : nil}"
+  end
+
   def extra_icons
     return {} unless configuration.extra_icons_path
 
     @extra_icons ||= {}
-    @extra_icons[extra_path] ||= begin
+    @extra_icons[file_cache_key_for(extra_path)] ||= begin
       data = MultiJson.load(extra_file_data)
       raise Error, "Extra icons file must contain a JSON object: #{extra_path}" unless data.is_a?(Hash)
 
@@ -73,7 +85,7 @@ module SvgIcon
 
   def extra_file_data
     @extra_file_data ||= {}
-    @extra_file_data[extra_path] ||= begin
+    @extra_file_data[file_cache_key_for(extra_path)] ||= begin
       path = extra_path
       raise Error, "Extra icons file not found: #{path}" unless File.exist?(path)
 
@@ -83,7 +95,7 @@ module SvgIcon
 
   def merge_extra_icons(base_icons)
     icons_set = base_icons["icons"]
-    raise Error, "Icon data must contain an 'icons' object: #{data_path}" unless icons_set.is_a?(Hash)
+    raise Error, "Icon data must contain an 'icons' object: #{resolve_icon_path}" unless icons_set.is_a?(Hash)
 
     return base_icons if extra_icons.empty?
 
@@ -93,6 +105,6 @@ module SvgIcon
   end
 
   def cache_key
-    "#{icon}:#{extra_path}"
+    "#{icon}:#{file_cache_key_for(resolve_icon_path)}:#{file_cache_key_for(extra_path)}"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: svg_icon
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - doabit
@@ -54,7 +54,8 @@ dependencies:
 description: Svg icon render helper for rails.
 email:
 - doinsist@gmail.com
-executables: []
+executables:
+- svg_icon
 extensions: []
 extra_rdoc_files: []
 files:
@@ -65,12 +66,17 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/superpowers/plans/2026-08-18-svg-icon-fetch-cli.md
+- docs/superpowers/specs/2026-08-18-svg-icon-fetch-design.md
+- exe/svg_icon
 - lib/data/bi.json
 - lib/data/bx.json
 - lib/data/heroicons.json
 - lib/data/lucide.json
 - lib/svg_icon.rb
+- lib/svg_icon/cli.rb
 - lib/svg_icon/configuration.rb
+- lib/svg_icon/fetcher.rb
 - lib/svg_icon/helper.rb
 - lib/svg_icon/version.rb
 - svg_icon.gemspec