shadwire 0.2.0

data/lib/shadwire/dependencies.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Shadwire
+  # Applies a component's non-file dependencies to a consuming Rails app: gems
+  # (via `bundle add`), importmap pins, and the Tailwind `@import`. Each method
+  # detects what is missing, then applies only when told to (`yes:` or a truthy
+  # `confirm:` callback) — the command owns the prompting. On an unsupported
+  # stack (no importmap / no tailwindcss-rails) it returns manual instructions
+  # and mutates nothing.
+  #
+  # Every method returns a normalized result hash:
+  #   { applied: [...], skipped: [...], pending: [...], manual: [...], failed: [...] }
+  #
+  # `failed` carries the things we tried to apply and could not — a `bundle add`
+  # that exited non-zero, above all. Callers must surface it and exit non-zero:
+  # reporting a gem as installed when it is not leaves the app raising
+  # `uninitialized constant ViewComponent` at request time, which looks unrelated
+  # to the install that caused it.
+  class Dependencies
+    # Runs a shell command in the app root, isolated from the CLI's own bundle.
+    DEFAULT_RUNNER = lambda do |cmd, chdir:|
+      require "bundler"
+      Bundler.with_unbundled_env { system(*cmd, chdir: chdir) }
+    end
+
+    # Raises when any of the given result hashes reports something it failed to
+    # apply, so a command that could not install a dependency exits non-zero
+    # instead of claiming success.
+    def self.raise_on_failure!(*results)
+      failed = results.flat_map { |result| Array(result[:failed]) }.uniq
+      return if failed.empty?
+
+      raise Error, "Failed to install: #{failed.join(", ")}. " \
+                   "Run `bundle add #{failed.join(" ")}` in the app and re-run this command."
+    end
+
+    def initialize(project, runner: DEFAULT_RUNNER)
+      @project = project
+      @runner = runner
+    end
+
+    # Ensures each gem name is present, running `bundle add <missing...>`.
+    def ensure_gems(names, yes:, confirm: nil)
+      present = names.select { |name| @project.gem?(name) }
+      missing = names - present
+      return result(skipped: present) if missing.empty?
+
+      unless apply?(yes, confirm, "Add gems: #{missing.join(", ")} (bundle add)")
+        return result(skipped: present, pending: missing)
+      end
+
+      # `system` returns false on a non-zero exit and nil when the command could
+      # not be run at all; neither means the gems landed.
+      return result(skipped: present, failed: missing) unless @runner.call(["bundle", "add", *missing], chdir: @project.root)
+
+      result(applied: missing, skipped: present)
+    end
+
+    # Ensures each pin ({ "name" =>, "to" => }) exists in config/importmap.rb.
+    def ensure_importmap_pins(pins, yes:, confirm: nil)
+      # importmap? is true when the gem is in the Gemfile, but config/importmap.rb
+      # only exists once `importmap:install` has run — guard the read so an
+      # unconfigured app falls back to a manual instruction instead of crashing.
+      path = @project.importmap_path
+      unless @project.importmap? && File.exist?(path)
+        return result(manual: pins.map { |p| manual_pin_instruction(p) })
+      end
+
+      content = File.read(path)
+      present, missing = pins.partition { |pin| pin_present?(content, pin) }
+      return result(skipped: present.map { |p| p["name"] }) if missing.empty?
+
+      names = missing.map { |p| p["name"] }
+      unless apply?(yes, confirm, "Add importmap pins: #{names.join(", ")}")
+        return result(skipped: present.map { |p| p["name"] }, pending: names)
+      end
+
+      appended = content
+      appended += "\n" unless appended.end_with?("\n")
+      missing.each { |pin| appended += %(pin "#{pin["name"]}", to: "#{pin["to"]}"\n) }
+      File.write(path, appended)
+      result(applied: names, skipped: present.map { |p| p["name"] })
+    end
+
+    # Ensures `@import "<relative>";` (pointing at the vendored shadwire.css)
+    # appears after `@import "tailwindcss";` in the Tailwind css entry.
+    def ensure_tailwind_import(vendor_css_target, css_entry: "app/assets/tailwind/application.css", yes:, confirm: nil)
+      css_path = @project.tailwind_css_path(css_entry)
+      unless @project.tailwindcss_rails? && File.exist?(css_path)
+        return result(manual: [manual_tailwind_instruction(vendor_css_target, css_entry)])
+      end
+
+      relative = relative_import(vendor_css_target, css_entry)
+      content = File.read(css_path)
+      return result(skipped: [relative]) if content.include?(%(@import "#{relative}"))
+
+      unless apply?(yes, confirm, "Add Tailwind import: #{relative}")
+        return result(pending: [relative])
+      end
+
+      File.write(css_path, insert_import(content, relative))
+      result(applied: [relative])
+    end
+
+    private
+
+    def result(applied: [], skipped: [], pending: [], manual: [], failed: [])
+      { applied:, skipped:, pending:, manual:, failed: }
+    end
+
+    def apply?(yes, confirm, description)
+      yes || !!confirm&.call(description)
+    end
+
+    def pin_present?(content, pin)
+      content.match?(/^\s*pin\s+["']#{Regexp.escape(pin["name"])}["']/)
+    end
+
+    def relative_import(vendor_css_target, css_entry)
+      Pathname(vendor_css_target).relative_path_from(Pathname(css_entry).dirname).to_s
+    end
+
+    # Inserts the import right after the `@import "tailwindcss";` line, or at the
+    # top when that line is absent.
+    def insert_import(content, relative)
+      import_line = %(@import "#{relative}";)
+      lines = content.lines
+      index = lines.index { |line| line.match?(/^\s*@import\s+["']tailwindcss["']/) }
+      if index
+        lines.insert(index + 1, "#{import_line}\n")
+      else
+        lines.unshift("#{import_line}\n")
+      end
+      lines.join
+    end
+
+    def manual_pin_instruction(pin)
+      %(Add to config/importmap.rb: pin "#{pin["name"]}", to: "#{pin["to"]}")
+    end
+
+    def manual_tailwind_instruction(vendor_css_target, css_entry)
+      relative = relative_import(vendor_css_target, css_entry)
+      %(Add to #{css_entry} after `@import "tailwindcss";`: @import "#{relative}";)
+    end
+  end
+end

data/lib/shadwire/differ.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Shadwire
+  # Minimal line-based unified diff, stdlib only — no diff gem. Used by `diff`
+  # and `update` to show how a locally-edited file drifts from the registry copy.
+  # Returns "" when the two texts are identical. Output normalizes line endings
+  # (each rendered line is chomped) since it is for human display, not patching;
+  # byte-exact drift detection is done by the caller comparing raw content.
+  module Differ
+    CONTEXT = 3
+
+    # An edit is [kind, old_index_or_nil, new_index_or_nil, text] where kind is
+    # one of :eq, :del, :ins.
+
+    module_function
+
+    def unified(old_text, new_text, path: nil)
+      return "" if old_text == new_text
+
+      edits = backtrack(lcs_table(old_text.lines, new_text.lines), old_text.lines, new_text.lines)
+      hunks = group(edits)
+      return "" if hunks.empty?
+
+      render(hunks, path)
+    end
+
+    # Longest-common-subsequence length table over the two line arrays.
+    def lcs_table(a, b)
+      table = Array.new(a.length + 1) { Array.new(b.length + 1, 0) }
+      a.each_index do |i|
+        b.each_index do |j|
+          table[i + 1][j + 1] = a[i] == b[j] ? table[i][j] + 1 : [table[i][j + 1], table[i + 1][j]].max
+        end
+      end
+      table
+    end
+
+    # Walks the table from the bottom-right to recover the edit sequence.
+    def backtrack(table, a, b)
+      edits = []
+      i = a.length
+      j = b.length
+      while i.positive? || j.positive?
+        if i.positive? && j.positive? && a[i - 1] == b[j - 1]
+          edits.unshift([:eq, i - 1, j - 1, a[i - 1]])
+          i -= 1
+          j -= 1
+        elsif j.positive? && (i.zero? || table[i][j - 1] >= table[i - 1][j])
+          edits.unshift([:ins, nil, j - 1, b[j - 1]])
+          j -= 1
+        else
+          edits.unshift([:del, i - 1, nil, a[i - 1]])
+          i -= 1
+        end
+      end
+      edits
+    end
+
+    # Groups changed edits into hunks, each padded with CONTEXT lines and merged
+    # when they overlap.
+    def group(edits)
+      ranges = []
+      edits.each_index.select { |k| edits[k][0] != :eq }.each do |k|
+        lo = [k - CONTEXT, 0].max
+        hi = [k + CONTEXT, edits.length - 1].min
+        if ranges.any? && lo <= ranges.last[1] + 1
+          ranges.last[1] = [ranges.last[1], hi].max
+        else
+          ranges << [lo, hi]
+        end
+      end
+      ranges.map { |lo, hi| edits[lo..hi] }
+    end
+
+    def render(hunks, path)
+      lines = []
+      lines << "--- a/#{path}" << "+++ b/#{path}" if path
+      hunks.each do |hunk|
+        lines << header(hunk)
+        hunk.each { |kind, _, _, text| lines << "#{prefix(kind)}#{text.chomp}" }
+      end
+      "#{lines.join("\n")}\n"
+    end
+
+    def header(hunk)
+      old = hunk.reject { |kind, *| kind == :ins }
+      new = hunk.reject { |kind, *| kind == :del }
+      old_start = (old.first&.at(1) || 0) + 1
+      new_start = (new.first&.at(2) || 0) + 1
+      "@@ -#{old_start},#{old.size} +#{new_start},#{new.size} @@"
+    end
+
+    def prefix(kind)
+      { eq: " ", del: "-", ins: "+" }.fetch(kind)
+    end
+  end
+end

data/lib/shadwire/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Shadwire
+  class Error < StandardError; end
+  class RegistryError < Error; end
+  class ConfigError < Error; end
+  class ProjectError < Error; end
+end

data/lib/shadwire/installer.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module Shadwire
+  # Writes published registry file entries into a consuming Rails app, applying
+  # the same safety checks bin/sync_registry enforces. It is non-interactive:
+  # the overwrite policy and an optional confirm callable are injected so that
+  # commands own the UI and tests stay deterministic.
+  #
+  # A file entry is a Hash of the published shape:
+  #   { "target" => "app/.../x.rb", "type" => "component", "content" => "..." }
+  class Installer
+    # @param root [String, Pathname] the consuming app root
+    # @param overwrite [Symbol] :always, :never, or :prompt
+    # @param confirm [#call, nil] called with the target string when :prompt;
+    #   truthy result overwrites, falsy skips
+    def initialize(root, overwrite: :prompt, confirm: nil)
+      @root = Pathname(root).expand_path
+      @overwrite = overwrite
+      @confirm = confirm
+    end
+
+    # Validates all targets (fail-fast), then writes.
+    # @param files [Array<Hash>] flat array of published file entries
+    # @return [Hash] { written: [target strings], skipped: [target strings] }
+    def install(files)
+      planned = validate(files)
+
+      written = []
+      skipped = []
+
+      planned.each do |target, content|
+        path = @root.join(target)
+
+        if path.exist? && !overwrite?(target)
+          skipped << target
+          next
+        end
+
+        FileUtils.mkdir_p(path.dirname)
+        path.write(content)
+        written << target
+      end
+
+      { written:, skipped: }
+    end
+
+    private
+
+    # Runs the escape-path and conflict checks before any write, de-duplicating
+    # identical (target, content) entries. Returns target => content pairs in
+    # first-seen order.
+    def validate(files)
+      seen = {}
+
+      files.each do |file|
+        target = file.fetch("target")
+        content = file.fetch("content")
+        absolute = @root.join(target).expand_path
+
+        unless inside_directory?(absolute, @root)
+          raise RegistryError, "Unsafe install target escapes app root: #{target}"
+        end
+
+        if seen.key?(target) && seen[target] != content
+          raise RegistryError, "Conflicting install target: #{target} maps to two different contents"
+        end
+
+        seen[target] = content
+      end
+
+      seen
+    end
+
+    def overwrite?(target)
+      case @overwrite
+      when :always then true
+      when :never then false
+      when :prompt then !!@confirm&.call(target)
+      else false
+      end
+    end
+
+    def inside_directory?(path, directory)
+      relative = path.relative_path_from(directory)
+      relative.each_filename.first != ".."
+    end
+  end
+end

data/lib/shadwire/project.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Shadwire
+  # Detects a consuming Rails app and its front-end stack by inspecting the
+  # Gemfile / Gemfile.lock and a few conventional files. Pure filesystem reads —
+  # never loads the app or Bundler.
+  class Project
+    attr_reader :root
+
+    def initialize(root)
+      @root = root.to_s
+    end
+
+    def rails?
+      File.exist?(path("config/application.rb")) || gem?("rails")
+    end
+
+    # True when the gem is declared in Gemfile.lock (authoritative when present)
+    # or the Gemfile.
+    def gem?(name)
+      (File.exist?(lockfile_path) && lock_declares?(name)) || gemfile_declares?(name)
+    end
+
+    def importmap?
+      gem?("importmap-rails") || File.exist?(importmap_path)
+    end
+
+    def tailwindcss_rails?
+      gem?("tailwindcss-rails")
+    end
+
+    def stimulus?
+      gem?("stimulus-rails") || File.exist?(path("app/javascript/controllers/index.js"))
+    end
+
+    def importmap_path
+      path("config/importmap.rb")
+    end
+
+    # Rails includes every app/helpers/**/*_helper.rb module into views unless an
+    # app opts out. When it does, the Ui::*Helper modules need per-controller
+    # `helper` calls, so `status` surfaces it.
+    def include_all_helpers?
+      config = path("config/application.rb")
+      return true unless File.exist?(config)
+
+      !File.read(config).match?(/include_all_helpers\s*=\s*false/)
+    end
+
+    # A monolithic app/helpers/ui_helper.rb left over from before helpers were
+    # split per item. No longer published; safe for the app to delete.
+    def legacy_helper?
+      File.exist?(path("app/helpers/ui_helper.rb"))
+    end
+
+    def tailwind_css_path(relative = "app/assets/tailwind/application.css")
+      path(relative)
+    end
+
+    # Raises ProjectError unless this looks like a Rails app.
+    def raise_unless_rails!
+      return if rails?
+
+      raise ProjectError,
+            "Not a Rails app: no config/application.rb or `gem \"rails\"` found in #{@root}"
+    end
+
+    private
+
+    def path(relative)
+      File.join(@root, relative)
+    end
+
+    def gemfile_path
+      path("Gemfile")
+    end
+
+    def lockfile_path
+      path("Gemfile.lock")
+    end
+
+    def gemfile_declares?(name)
+      File.exist?(gemfile_path) &&
+        File.read(gemfile_path).match?(/^\s*gem\s+["']#{Regexp.escape(name)}["']/)
+    end
+
+    def lock_declares?(name)
+      File.read(lockfile_path).match?(/^\s+#{Regexp.escape(name)} \(/)
+    end
+  end
+end

data/lib/shadwire/registry_client.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Shadwire
+  # Fetches the published registry over file:// or http(s)://.
+  # Both #index and #item are memoized within the instance.
+  class RegistryClient
+    def initialize(base_url)
+      # Normalise: drop any trailing slash so URL building is consistent.
+      @base_url = base_url.chomp("/")
+      @cache = {}
+    end
+
+    # Returns the parsed index.json hash (memoized).
+    def index
+      @cache[:__index__] ||= fetch("index.json")
+    end
+
+    # Returns the parsed {name}.json hash (memoized per name).
+    # Raises Shadwire::RegistryError if the item is not found.
+    def item(name)
+      @cache[name] ||= fetch("#{name}.json", name:)
+    end
+
+    private
+
+    def fetch(filename, name: nil)
+      url = "#{@base_url}/#{filename}"
+      if @base_url.start_with?("file://")
+        fetch_file(url, name:)
+      else
+        fetch_http(url, name:)
+      end
+    end
+
+    def fetch_file(url, name: nil)
+      # file:///abs/path/... → /abs/path/...
+      local_path = url.sub(/\Afile:\/\//, "")
+      unless File.exist?(local_path)
+        raise RegistryError, missing_message(name, url)
+      end
+
+      parse(File.read(local_path), url)
+    end
+
+    def fetch_http(url, name: nil)
+      require "net/http"
+      require "uri"
+
+      uri = URI.parse(url)
+      response = Net::HTTP.get_response(uri)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise RegistryError, missing_message(name, url, code: response.code)
+      end
+
+      parse(response.body, url)
+    rescue SocketError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError => e
+      # An offline machine, a DNS failure or a TLS problem is an ordinary
+      # condition here, not something to surface as a Ruby backtrace.
+      raise RegistryError, "Could not reach the registry at #{url}: #{e.message}"
+    end
+
+    # A registry that serves HTML (a 200 error page, a captive portal) would
+    # otherwise blow up as a bare JSON::ParserError.
+    def parse(body, url)
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise RegistryError, "Registry response from #{url} is not valid JSON: #{e.message}"
+    end
+
+    def missing_message(name, url, code: nil)
+      label = name ? "item #{name.inspect}" : "index"
+      suffix = code ? " (HTTP #{code})" : ""
+      "Registry #{label} not found at #{url}#{suffix}"
+    end
+  end
+end

data/lib/shadwire/resolver.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Shadwire
+  # Resolves a list of item names to a de-duplicated, dependency-first ordered
+  # array of parsed item hashes.  Uses post-order DFS so every dependency
+  # appears before the item that requires it.  Unknown names — whether
+  # top-level or pulled in transitively — raise Shadwire::RegistryError.
+  class Resolver
+    # Public API: returns an Array of item Hashes, dependency-first.
+    def self.expand(names, client)
+      new(client).expand(names)
+    end
+
+    def initialize(client)
+      @client  = client
+      @visited = {}   # name => true once fully processed
+      @result  = []
+    end
+
+    def expand(names)
+      names.each { |name| visit(name) }
+      @result
+    end
+
+    private
+
+    def visit(name)
+      return if @visited[name]
+
+      # Mark before recursing to break potential cycles and prevent double-add.
+      @visited[name] = true
+
+      # Fetch the item; RegistryError propagates on 404 / missing file.
+      data = @client.item(name)
+
+      # Recurse into dependencies first (post-order).
+      Array(data["registryDependencies"]).each { |dep| visit(dep) }
+
+      # Add this item after all its deps are in the result.
+      @result << data
+    end
+  end
+end

data/lib/shadwire/ui.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Shadwire
+  # Thin terminal-and-agent-friendly IO wrapper. Output streams and the confirm
+  # behavior are injectable so commands stay decoupled from Thor and tests can
+  # capture output and answer prompts deterministically. With yes: true every
+  # confirmation is auto-accepted (the agent/CI path).
+  class UI
+    def initialize(out: $stdout, err: $stderr, yes: false, confirm_proc: nil)
+      @out = out
+      @err = err
+      @yes = yes
+      @confirm_proc = confirm_proc
+    end
+
+    def say(message)
+      @out.puts(message)
+    end
+
+    def warn(message)
+      @err.puts(message)
+    end
+
+    def error(message)
+      @err.puts(message)
+    end
+
+    def confirm?(question, default: false)
+      return true if @yes
+      return !!@confirm_proc.call(question) if @confirm_proc
+
+      prompt(question, default)
+    end
+
+    private
+
+    def prompt(question, default)
+      suffix = default ? "[Y/n]" : "[y/N]"
+      @out.print("#{question} #{suffix} ")
+      answer = $stdin.gets
+      return default if answer.nil? || answer.strip.empty?
+
+      answer.strip.downcase.start_with?("y")
+    end
+  end
+end

data/lib/shadwire/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Shadwire
+  VERSION = "0.2.0"
+end

data/lib/shadwire.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "shadwire/version"
+require_relative "shadwire/errors"
+require_relative "shadwire/config"
+require_relative "shadwire/project"
+require_relative "shadwire/registry_client"
+require_relative "shadwire/resolver"
+require_relative "shadwire/installer"
+require_relative "shadwire/dependencies"
+require_relative "shadwire/differ"
+require_relative "shadwire/ui"
+require_relative "shadwire/commands/init"
+require_relative "shadwire/commands/add"
+require_relative "shadwire/commands/list"
+require_relative "shadwire/commands/search"
+require_relative "shadwire/commands/info"
+require_relative "shadwire/commands/diff"
+require_relative "shadwire/commands/update"
+require_relative "shadwire/commands/remove"
+require_relative "shadwire/commands/status"
+require_relative "shadwire/cli"