shadwire 0.2.0

data/lib/shadwire/commands/list.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Shadwire
+  module Commands
+    # Lists the registry catalog: one entry (name/type/title/description) per
+    # published item. Read-only — needs a registry but no Rails app. With
+    # json: true it emits the catalog array; otherwise a "name — title" line each.
+    class List
+      def initialize(root:, registry: nil, json: false, ui: UI.new)
+        @root = root.to_s
+        @registry_override = registry
+        @json = json
+        @ui = ui
+      end
+
+      def call
+        client = RegistryClient.new(@registry_override || Config.load(@root).registry)
+        items = client.index.fetch("items", [])
+        emit(items)
+        items
+      end
+
+      private
+
+      def emit(items)
+        if @json
+          @ui.say(JSON.generate(items))
+        else
+          items.each { |item| @ui.say("#{item["name"]} — #{item["title"]}") }
+        end
+      end
+    end
+  end
+end

data/lib/shadwire/commands/remove.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Shadwire
+  module Commands
+    # Uninstalls one or more components. It deletes only files unique to the
+    # removed items — never the shared base (ui_component/ui_helper/shadwire.css)
+    # and never a file still listed by another installed entry — then prunes any
+    # emptied directory under the components root and drops the items from
+    # shadwire.json. Importmap pins that no remaining component uses are reported
+    # (not auto-removed — dep cleanup is left to the user). Confirms first unless
+    # --yes.
+    class Remove
+      def initialize(root:, names:, yes: false, registry: nil, json: false, ui: UI.new(yes:))
+        @root = root.to_s
+        @names = names
+        @yes = yes
+        @registry_override = registry
+        @json = json
+        @ui = ui
+      end
+
+      def call
+        raise Shadwire::Error, "remove requires at least one component name" if @names.empty?
+
+        Project.new(@root).raise_unless_rails!
+        config = Config.load(@root)
+        client = RegistryClient.new(@registry_override || config.registry)
+        @names.each do |name|
+          raise Shadwire::Error, "#{name} is not installed" unless config.installed.key?(name)
+        end
+
+        base_targets = client.index.fetch("base").fetch("files").map { |file| file["target"] }
+        removed_targets = targets_for(config, @names)
+        remaining = config.installed.keys - @names
+        other_targets = targets_for(config, remaining)
+
+        deletable = (removed_targets - base_targets - other_targets).select { |target| on_disk?(target) }
+        kept_shared = base_targets & removed_targets
+
+        unless @yes || @ui.confirm?("Remove #{deletable.size} files for #{@names.join(", ")}?")
+          @ui.say("Aborted; nothing removed.")
+          return { removed: [], deleted: [], keptShared: kept_shared, unusedPins: [] }
+        end
+
+        deletable.each { |target| File.delete(File.join(@root, target)) }
+        prune_empty_dirs(deletable, config)
+
+        @names.each { |name| config.forget(name) }
+        config.save
+
+        result = {
+          removed: @names,
+          deleted: deletable,
+          keptShared: kept_shared,
+          unusedPins: unused_pins(client, remaining)
+        }
+        emit(result)
+        result
+      end
+
+      private
+
+      def targets_for(config, names)
+        names.flat_map { |name| config.installed[name]["files"] }.uniq
+      end
+
+      def on_disk?(target)
+        File.exist?(File.join(@root, target))
+      end
+
+      # Removes now-empty directories from each deleted file's dir upward, bounded
+      # strictly inside the components root (never the root itself or above).
+      def prune_empty_dirs(deleted, config)
+        components_root = File.expand_path(File.join(@root, config.aliases.fetch("components", "app/components")))
+        deleted.each do |target|
+          dir = File.dirname(File.expand_path(File.join(@root, target)))
+          while dir.start_with?("#{components_root}#{File::SEPARATOR}") && File.directory?(dir) && Dir.empty?(dir)
+            Dir.rmdir(dir)
+            dir = File.dirname(dir)
+          end
+        end
+      end
+
+      # Pins of the removed items that no still-installed item pins.
+      def unused_pins(client, remaining)
+        remaining_names = remaining.map { |name| pins_for(client, name).map { |pin| pin["name"] } }.flatten
+        @names.flat_map { |name| pins_for(client, name) }
+              .reject { |pin| remaining_names.include?(pin["name"]) }
+              .uniq
+      end
+
+      def pins_for(client, name)
+        Array(client.item(name)["importmap"])
+      end
+
+      def emit(result)
+        return @ui.say(JSON.generate(result)) if @json
+
+        human(result)
+      end
+
+      def human(result)
+        return if result[:removed].empty?
+
+        @ui.say("Removed #{result[:removed].join(", ")}.")
+        result[:deleted].each { |target| @ui.say("  delete  #{target}") }
+        result[:keptShared].each { |target| @ui.say("  keep    #{target} (shared)") }
+        result[:unusedPins].each do |pin|
+          @ui.say(%(  note    importmap pin "#{pin["name"]}" is now unused; review config/importmap.rb))
+        end
+      end
+    end
+  end
+end

data/lib/shadwire/commands/search.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Shadwire
+  module Commands
+    # Filters the registry catalog by a case-insensitive substring match on an
+    # item's name, title, description, or whenToUse. Read-only. With json: true
+    # it emits the matching catalog entries; otherwise a "name — title" line each.
+    #
+    # whenToUse is searched because it is where the disambiguating vocabulary
+    # lives ("form", "modal", "overlay"); without it a search for "form" misses
+    # most of the form controls.
+    class Search
+      SEARCHABLE = %w[name title description whenToUse].freeze
+
+      def initialize(root:, query:, registry: nil, json: false, ui: UI.new)
+        @root = root.to_s
+        @query = query.to_s
+        @registry_override = registry
+        @json = json
+        @ui = ui
+      end
+
+      def call
+        client = RegistryClient.new(@registry_override || Config.load(@root).registry)
+        matches = filter(client.index.fetch("items", []))
+        emit(matches)
+        matches
+      end
+
+      private
+
+      def filter(items)
+        needle = @query.downcase
+        items.select do |item|
+          SEARCHABLE.any? { |key| item[key].to_s.downcase.include?(needle) }
+        end
+      end
+
+      def emit(matches)
+        if @json
+          @ui.say(JSON.generate(matches))
+        elsif matches.empty?
+          @ui.say(%(No matches for "#{@query}".))
+        else
+          matches.each { |item| @ui.say("#{item["name"]} — #{item["title"]}") }
+        end
+      end
+    end
+  end
+end

data/lib/shadwire/commands/status.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Shadwire
+  module Commands
+    # Reports the consuming app's Shadwire context: stack detection, the
+    # components installed with the helper methods they actually define, and
+    # per-component drift.
+    #
+    # This is the payload the agent skill injects, so it must always succeed. A
+    # directory that is not a Rails app, a missing shadwire.json, or an
+    # unreachable registry are all reported as data — never raised — because an
+    # exception here would leave an agent starting from a backtrace instead of
+    # its project context.
+    class Status
+      def initialize(root:, registry: nil, json: false, ui: UI.new)
+        @root = root.to_s
+        @registry_override = registry
+        @json = json
+        @ui = ui
+      end
+
+      def call
+        project = Project.new(@root)
+        config = Config.load(@root)
+        result = context(project, config)
+
+        begin
+          client = RegistryClient.new(@registry_override || config.registry)
+          result["registryVersion"] = client.index["version"]
+          result["availableCount"] = Array(client.index["items"]).size
+          result["installed"] = installed(config, client)
+        rescue Shadwire::Error => e
+          result["registryError"] = e.message
+        end
+
+        emit(result)
+        result
+      end
+
+      private
+
+      def context(project, config)
+        {
+          "rails" => project.rails?,
+          "configPresent" => File.exist?(File.join(@root, Config::CONFIG_FILE)),
+          "registry" => @registry_override || config.registry,
+          "registryVersion" => nil,
+          "availableCount" => nil,
+          "stack" => {
+            "importmap" => project.importmap?,
+            "stimulus" => project.stimulus?,
+            "tailwindcssRails" => project.tailwindcss_rails?
+          },
+          "gems" => {
+            "view_component" => project.gem?("view_component"),
+            "lucide-rails" => project.gem?("lucide-rails")
+          },
+          "tailwind" => {
+            "css" => config.tailwind_css,
+            "importPresent" => tailwind_import?(config)
+          },
+          "helpers" => {
+            "includeAllHelpers" => project.include_all_helpers?,
+            "legacyHelperPresent" => project.legacy_helper?
+          },
+          "installed" => []
+        }
+      end
+
+      def tailwind_import?(config)
+        path = File.join(@root, config.tailwind_css)
+        File.exist?(path) && File.read(path).include?("shadwire.css")
+      end
+
+      def installed(config, client)
+        config.installed.map do |name, entry|
+          item = client.item(name)
+          components = Array(item.dig("api", "components"))
+
+          {
+            "name" => name,
+            "version" => entry["version"],
+            "drift" => drift(item),
+            "helpers" => components.filter_map { |component| component["helper"] },
+            "classes" => components.filter_map { |component| component["class"] }
+          }
+        rescue Shadwire::Error
+          # The item vanished from the registry; report it rather than failing.
+          { "name" => name, "version" => entry["version"], "drift" => "unknown",
+            "helpers" => [], "classes" => [] }
+        end
+      end
+
+      # Worst status across the item's files: missing beats modified beats
+      # unchanged, so a single number tells an agent whether to look closer.
+      def drift(item)
+        statuses = Array(item["files"]).map do |file|
+          path = File.join(@root, file["target"])
+          next "missing" unless File.exist?(path)
+
+          File.read(path) == file["content"] ? "unchanged" : "modified"
+        end
+
+        return "missing" if statuses.include?("missing")
+
+        statuses.include?("modified") ? "modified" : "unchanged"
+      end
+
+      def emit(result)
+        return @ui.say(JSON.generate(result)) if @json
+
+        human(result)
+      end
+
+      def human(result)
+        @ui.say("Rails app:  #{yes_no(result["rails"])}    shadwire.json: #{yes_no(result["configPresent"])}")
+        @ui.say("Registry:   #{result["registry"]} (#{result["registryVersion"] || "unavailable"})")
+        @ui.say("Stack:      importmap=#{result.dig("stack", "importmap")} " \
+                "stimulus=#{result.dig("stack", "stimulus")} " \
+                "tailwindcss-rails=#{result.dig("stack", "tailwindcssRails")}")
+        @ui.say("Installed (#{result["installed"].size} of #{result["availableCount"] || "?"}):")
+        result["installed"].each do |item|
+          @ui.say("  #{item["drift"].ljust(9)} #{item["name"]}  #{item["helpers"].join(", ")}")
+        end
+
+        @ui.warn("Registry unavailable: #{result["registryError"]}") if result["registryError"]
+        return unless result.dig("helpers", "legacyHelperPresent")
+
+        @ui.warn("Note: app/helpers/ui_helper.rb is left over from an older install; " \
+                 "helpers now live in app/helpers/ui/ and it can be deleted.")
+      end
+
+      def yes_no(value)
+        value ? "yes" : "no"
+      end
+    end
+  end
+end

data/lib/shadwire/commands/update.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Shadwire
+  module Commands
+    # Re-applies the registry version of installed components. With no names it
+    # updates every installed item. It surfaces local drift (via Differ) before
+    # writing so edits are never clobbered silently, then reuses add's overwrite
+    # policy, dependency handling, and installed bookkeeping. --yes/--overwrite
+    # skip the per-file prompt; --no-deps limits the update to the named items.
+    class Update
+      def initialize(root:, names: [], yes: false, overwrite: false, no_deps: false,
+                     registry: nil, json: false, ui: UI.new(yes:), runner: Dependencies::DEFAULT_RUNNER)
+        @root = root.to_s
+        @names = names
+        @yes = yes
+        @overwrite = overwrite
+        @no_deps = no_deps
+        @registry_override = registry
+        @json = json
+        @ui = ui
+        @runner = runner
+      end
+
+      def call
+        project = Project.new(@root)
+        project.raise_unless_rails!
+
+        config = Config.load(@root)
+        client = RegistryClient.new(@registry_override || config.registry)
+        targets = resolve_targets(config)
+
+        items = resolve_items(targets, client)
+        files = items.flat_map { |item| item.fetch("files") }
+
+        diffs = compute_diffs(files) # read local drift before any overwrite
+        report = install_files(files)
+
+        deps = Dependencies.new(project, runner: @runner)
+        dep_confirm = ->(desc) { @ui.confirm?(desc) }
+        gems = deps.ensure_gems(union(items, "gems"), yes: @yes, confirm: dep_confirm)
+        pins = deps.ensure_importmap_pins(union(items, "importmap"), yes: @yes, confirm: dep_confirm)
+
+        record_installed(config, client, targets, items)
+        config.save
+
+        result = { updated: targets, report:, gems:, pins:, diffs: }
+        emit(result)
+        Dependencies.raise_on_failure!(gems, pins)
+
+        result
+      end
+
+      private
+
+      def resolve_targets(config)
+        targets = @names.empty? ? config.installed.keys : @names
+        targets.each do |name|
+          raise Shadwire::Error, "#{name} is not installed" unless config.installed.key?(name)
+        end
+        targets
+      end
+
+      def resolve_items(targets, client)
+        @no_deps ? targets.map { |name| client.item(name) } : Resolver.expand(targets, client)
+      end
+
+      def compute_diffs(files)
+        diffs = {}
+        files.each do |file|
+          target = file["target"]
+          path = File.join(@root, target)
+          next unless File.exist?(path)
+
+          local = File.read(path)
+          diffs[target] = Differ.unified(local, file["content"], path: target) unless local == file["content"]
+        end
+        diffs
+      end
+
+      def install_files(files)
+        if @yes || @overwrite
+          Installer.new(@root, overwrite: :always).install(files)
+        else
+          Installer.new(@root, overwrite: :prompt, confirm: content_aware_confirm(files)).install(files)
+        end
+      end
+
+      # Skips files whose on-disk content already matches the registry; prompts
+      # only for locally-modified files.
+      def content_aware_confirm(files)
+        by_target = files.to_h { |file| [file["target"], file["content"]] }
+        lambda do |target|
+          current = File.read(File.join(@root, target))
+          return false if current == by_target[target]
+
+          @ui.confirm?("Overwrite modified #{target}?")
+        end
+      end
+
+      def union(items, key)
+        items.flat_map { |item| Array(item[key]) }.uniq
+      end
+
+      def record_installed(config, client, targets, items)
+        by_name = items.to_h { |item| [item["name"], item] }
+        version = client.index["version"]
+        targets.each do |name|
+          item = by_name[name] || client.item(name)
+          file_targets = item.fetch("files").map { |file| file["target"] }
+          config.record_installed(name, version, file_targets)
+        end
+      end
+
+      def emit(result)
+        return @ui.say(JSON.generate(json_payload(result))) if @json
+
+        human(result)
+      end
+
+      # `overwritten` is the whole point: update clobbers local edits, and the
+      # human path prints the diff. Omitting it from JSON let an agent destroy
+      # customizations without ever being told they existed.
+      def json_payload(result)
+        {
+          updated: result[:updated],
+          written: result[:report][:written],
+          skipped: result[:report][:skipped],
+          overwritten: result[:diffs].keys & result[:report][:written],
+          diffs: result[:diffs],
+          gems: result[:gems][:applied],
+          gemsFailed: result[:gems][:failed],
+          pins: result[:pins][:applied],
+          pinsFailed: result[:pins][:failed]
+        }
+      end
+
+      def human(result)
+        @ui.say("Updated #{result[:updated].join(", ")}.")
+        result[:diffs].each_value { |rendered| @ui.say(rendered) }
+        result[:report][:written].each { |target| @ui.say("  write   #{target}") }
+        result[:report][:skipped].each { |target| @ui.say("  skip    #{target}") }
+      end
+    end
+  end
+end

data/lib/shadwire/config.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Shadwire
+  # Reads and writes a consuming Rails app's shadwire.json.
+  #
+  # On-disk JSON shape (mirrors shadcn's components.json conventions):
+  #
+  #   {
+  #     "registry": "https://edumoraes.github.io/shadwire/r",
+  #     "tailwind": { "css": "app/assets/tailwind/application.css" },
+  #     "aliases": {
+  #       "components":  "app/components",
+  #       "ui":          "app/components/ui",
+  #       "helpers":     "app/helpers",
+  #       "controllers": "app/javascript/controllers",
+  #       "vendorCss":   "vendor/shadwire"
+  #     },
+  #     "installed": {
+  #       "button": { "version": "1.0.0", "files": ["app/components/ui/button_component.rb"] }
+  #     }
+  #   }
+  class Config
+    CONFIG_FILE = "shadwire.json"
+
+    DEFAULTS = {
+      "registry" => "https://edumoraes.github.io/shadwire/r",
+      "tailwind" => { "css" => "app/assets/tailwind/application.css" },
+      "aliases" => {
+        "components"  => "app/components",
+        "ui"          => "app/components/ui",
+        "helpers"     => "app/helpers",
+        "controllers" => "app/javascript/controllers",
+        "vendorCss"   => "vendor/shadwire"
+      },
+      "installed" => {}
+    }.freeze
+
+    attr_reader :root, :tailwind_css, :aliases, :installed
+    attr_accessor :registry
+
+    # Loads shadwire.json from the given app root, or returns a Config with
+    # defaults when the file does not exist.
+    def self.load(root)
+      path = File.join(root, CONFIG_FILE)
+      data = File.exist?(path) ? parse(path) : JSON.parse(JSON.generate(DEFAULTS))
+      new(root, data)
+    end
+
+    # A hand-edited shadwire.json is common enough that a raw JSON::ParserError
+    # backtrace is the wrong answer; name the file and the problem.
+    def self.parse(path)
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError => e
+      raise ConfigError, "#{path} is not valid JSON: #{e.message}"
+    end
+
+    # Writes pretty JSON to <root>/shadwire.json.
+    def save
+      FileUtils.mkdir_p(@root)
+      File.write(File.join(@root, CONFIG_FILE), JSON.pretty_generate(to_h) + "\n")
+    end
+
+    # Records an installed component: installed[name] = { "version" => ..., "files" => [...] }.
+    def record_installed(name, version, files)
+      @installed[name] = { "version" => version, "files" => files }
+    end
+
+    # Removes an entry from installed.
+    def forget(name)
+      @installed.delete(name)
+    end
+
+    private
+
+    def initialize(root, data)
+      @root        = root
+      @registry    = data.fetch("registry",  DEFAULTS["registry"])
+      @tailwind_css = data.dig("tailwind", "css") || DEFAULTS.dig("tailwind", "css")
+      @aliases     = data.fetch("aliases",   JSON.parse(JSON.generate(DEFAULTS["aliases"])))
+      @installed   = data.fetch("installed", {})
+    end
+
+    def to_h
+      {
+        "registry" => @registry,
+        "tailwind" => { "css" => @tailwind_css },
+        "aliases"  => @aliases,
+        "installed" => @installed
+      }
+    end
+  end
+end