shadwire 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c857670a096593c58b47a25ad03b9c1613dd4386f54a7cc4f4ae84100960c7ff
-  data.tar.gz: 06b367750966cbcbaf8a26eabb229fdb80211a7379980b12ae71b7251d8cb7f2
+  metadata.gz: 6294368abb24616f95b0d9a751bb554ba5135904927f03e5d880c3b969448c2a
+  data.tar.gz: ebcf2c60b07a68b96d2c97d07759b05b44432bf634809e1e174958adf3ea51f9
 SHA512:
-  metadata.gz: 617cdd3e2b46c0cf2dd757e77eafe0a797144be2f18b7b85a96c40a94641d4dbfc575b4c905e058487f2ffd2d0dbb0c9f46a0a5f2737a1ee764db488305850b9
-  data.tar.gz: 62919522fee319ecc4706dc2e6b9ea4ab5b70b56d3bd5a7a41c005e2ae34a4004c3fd7cc44a0cee95b3f76f4108e5694e444e8157d34fa02ca99d4343fca9828
+  metadata.gz: e3db758ffe31655123b1460ec872f3ff001b68fa7c0f31e690eff757b1dd8a747af55fc50916ea9a855cfa0585a97c1077bab51930f07b68cb7a9887e85e5892
+  data.tar.gz: 91475dc299cd4f7a434684386696bb200c8dd8eb95a57f1d69b0696cfc3d3da045311d46b855e04b0d48fb52dc2f54633d86ea57e743345dd4676112d395c441

data/README.md

@@ -11,19 +11,29 @@ registry the CLI installs from over HTTP.
 ## Install
 
 ```bash
-bundle add shadwire --group development   # then run: bundle exec shadwire
-gem install shadwire                      # or globally, then run: shadwire
+gem install shadwire                       # global — then: shadwire init
+bundle add shadwire --group development    # in the app — then: bundle exec shadwire init
 ```
 
+`init` adds `shadwire` to the app's `development` group (if it is not there
+already) and writes the `bin/shadwire` binstub. That binstub is the canonical
+entry point: it resolves through the app's bundle, so everyone who installs the
+development group runs the same CLI version. `init` is the one command you run
+un-prefixed, because it is what creates the binstub.
+
+A bundle installed with `--without development` (common for deploy, and for some
+CI jobs) has no `shadwire`, so `bin/shadwire` will not run there. Install the
+development group in any job that runs the CLI — the drift check below, for one.
+
 Requires Ruby >= 3.2 and a Rails app (>= 7.1) using ViewComponent and Tailwind CSS.
 
 ## Commands
 
-Run `shadwire help COMMAND` for the built-in usage of any command.
+Run `bin/shadwire help COMMAND` for the built-in usage of any command.
 
 | Command | What it does | Flags (besides `--cwd`) |
 | --- | --- | --- |
-| `init` | Bootstrap Shadwire: write `shadwire.json`, install the shared base files (`ui_component.rb`, `shadwire.css`) and base gems, add the Tailwind `@import`. | `--yes`, `--registry URL`, `--force`, `--json` |
+| `init` | Bootstrap Shadwire: write `shadwire.json`, install the shared base files (`ui_component.rb`, `shadwire.css`) and base gems, add `shadwire` to the `development` group, write the `bin/shadwire` binstub, add the Tailwind `@import`. | `--yes`, `--registry URL`, `--force`, `--json` |
 | `add NAME...` | Install one or more components and their registry dependencies; apply their gems and importmap pins; record them in `shadwire.json`. | `--yes`, `--overwrite`, `--no-deps`, `--registry URL`, `--json` |
 | `list` | List every component in the registry catalog. | `--registry URL`, `--json` |
 | `search QUERY` | Search the catalog by name, title, or description. | `--registry URL`, `--json` |
@@ -43,6 +53,7 @@ the Shadwire agent skill injects it:
 {
   "rails": true, "configPresent": true, "registryVersion": "0.2.0",
   "stack": { "importmap": true, "stimulus": true, "tailwindcssRails": true },
+  "cli": { "gem": true, "binstub": true },
   "helpers": { "includeAllHelpers": true, "legacyHelperPresent": false },
   "installed": [
     { "name": "card", "drift": "unchanged",

data/lib/shadwire/binstub.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module Shadwire
+  # The canonical entry point a consuming app uses to run the CLI: bin/shadwire.
+  #
+  # The template is the shape Rails 8 generates for bin/rubocop and bin/brakeman,
+  # so the file reads as native to the app it lands in. Being a bundler binstub,
+  # it only works once `gem "shadwire"` is declared in the app's Gemfile —
+  # Commands::Init gates the write on that, because a binstub written without it
+  # raises Gem::LoadError on first run.
+  #
+  # Deliberately not routed through Installer: that writes published registry
+  # entries tracked in shadwire.json, and it never sets an execute bit.
+  module Binstub
+    PATH = "bin/shadwire"
+    MODE = 0o755
+
+    TEMPLATE = <<~RUBY
+      #!/usr/bin/env ruby
+      # frozen_string_literal: true
+      require "rubygems"
+      require "bundler/setup"
+      load Gem.bin_path("shadwire", "shadwire")
+    RUBY
+
+    # The gem that backs the binstub. `init` adds it, `status` reports it.
+    GEM = "shadwire"
+
+    def self.exist?(root)
+      File.exist?(File.join(root.to_s, PATH))
+    end
+
+    # Writes bin/shadwire unless it already exists.
+    #
+    # An existing binstub is left alone: `bundle binstubs shadwire` produces a
+    # different, working file, and it is not tracked in shadwire.json, so
+    # `shadwire diff` could never report that we replaced it.
+    #
+    # @param root [String, Pathname] the consuming app root
+    # @param force [Boolean] rewrite an existing binstub
+    # @return [Hash] { written: Boolean, skipped: Boolean }
+    def self.write(root, force: false)
+      path = Pathname(root).join(PATH)
+      return { written: false, skipped: true } if path.exist? && !force
+
+      FileUtils.mkdir_p(path.dirname)
+      path.write(TEMPLATE)
+      path.chmod(MODE)
+      { written: true, skipped: false }
+    end
+  end
+end

data/lib/shadwire/cli.rb

@@ -21,7 +21,7 @@ module Shadwire
                         desc: "Apply dependency changes without prompting"
     method_option :registry, type: :string, desc: "Registry base URL to install from"
     method_option :force, type: :boolean, default: false,
-                          desc: "Overwrite an existing shadwire.json"
+                          desc: "Reset shadwire.json and rewrite bin/shadwire, overwriting both"
     method_option :json, type: :boolean, default: false, desc: "Emit machine-readable JSON"
     def init
       run_command do |root, ui|

data/lib/shadwire/commands/init.rb

@@ -8,6 +8,12 @@ module Shadwire
     # files, and applies the base gems + the Tailwind @import (confirm-then-apply,
     # auto on yes:). Idempotent on re-run; --force resets shadwire.json.
     class Init
+      # The CLI gem is a development-time tool for the app, deliberately kept out
+      # of registry.json: the registry's gems are what the *components* need at
+      # runtime, and installed files carry no Shadwire dependency.
+      CLI_GEM = Binstub::GEM
+      CLI_GEM_GROUP = "development"
+
       def initialize(root:, registry: nil, yes: false, force: false, json: false,
                      ui: UI.new(yes:), runner: Dependencies::DEFAULT_RUNNER)
         @root = root.to_s
@@ -31,16 +37,21 @@ module Shadwire
 
         deps = Dependencies.new(project, runner: @runner)
         confirm = ->(desc) { @ui.confirm?(desc) }
-        gems = deps.ensure_gems(Array(base["gems"]), yes: @yes, confirm:)
+        base_gems = deps.ensure_gems(Array(base["gems"]), yes: @yes, confirm:)
+        cli_gem = deps.ensure_gems([CLI_GEM], yes: @yes, confirm:, group: CLI_GEM_GROUP)
+        gems = merge_gem_results(base_gems, cli_gem)
         tailwind = deps.ensure_tailwind_import(
           vendor_css_target(config, base), css_entry: config.tailwind_css, yes: @yes, confirm:
         )
+        binstub = write_binstub(cli_gem)
 
         config.save
         warn_missing_stack(project)
-        result = { config:, report:, gems:, tailwind: }
+        result = { config:, report:, gems:, gem_results: [base_gems, cli_gem], tailwind:, binstub: }
         emit(result)
-        Dependencies.raise_on_failure!(gems)
+        # Passed separately, not merged: each result carries its own group, so
+        # the recovery command it suggests matches the one that failed.
+        Dependencies.raise_on_failure!(base_gems, cli_gem)
 
         result
       end
@@ -55,6 +66,27 @@ module Shadwire
         config
       end
 
+      def merge_gem_results(*results)
+        %i[applied skipped pending manual failed]
+          .to_h { |key| [key, results.flat_map { |result| result[key] }] }
+      end
+
+      # Only write the binstub once `shadwire` is actually declared in the app's
+      # Gemfile — a bundler binstub without it raises Gem::LoadError on first run.
+      #
+      # The gate reads the ensure_gems result rather than re-reading the Gemfile:
+      # it is a direct record of what the command did, and it does not depend on
+      # `bundle add` writing a line the Project#gem? regex recognizes.
+      def write_binstub(cli_gem)
+        present = (cli_gem[:applied] + cli_gem[:skipped]).include?(CLI_GEM)
+        # An existing binstub without the gem is a different problem from a
+        # missing one: telling someone to create a file that is already there
+        # buries the real issue, which is that it cannot run.
+        return { status: Binstub.exist?(@root) ? :unusable : :unavailable } unless present
+
+        Binstub.write(@root, force: @force)[:written] ? { status: :written } : { status: :skipped }
+      end
+
       def vendor_css_target(config, base)
         File.join(config.aliases.fetch("vendorCss", "vendor/shadwire"), base.dig("tailwind", "css"))
       end
@@ -74,7 +106,7 @@ module Shadwire
       def emit(result)
         return @ui.say(JSON.generate(json_payload(result))) if @json
 
-        print_summary(result[:report], result[:gems], result[:tailwind])
+        print_summary(result[:report], result[:gem_results], result[:tailwind], result[:binstub])
       end
 
       def json_payload(result)
@@ -83,18 +115,41 @@ module Shadwire
           "gems" => { "applied" => result[:gems][:applied], "pending" => result[:gems][:pending],
                       "failed" => result[:gems][:failed] },
           "tailwind" => { "applied" => result[:tailwind][:applied], "manual" => result[:tailwind][:manual] },
+          "binstub" => { "path" => Binstub::PATH,
+                         "written" => result[:binstub][:status] == :written,
+                         "skipped" => result[:binstub][:status] == :skipped },
           "registry" => result[:config].registry
         }
       end
 
-      def print_summary(report, gems, tailwind)
+      def print_summary(report, gem_results, tailwind, binstub)
         @ui.say("Initialized shadwire (#{report[:written].size} base files).")
         report[:written].each { |t| @ui.say("  create  #{t}") }
-        gems[:applied].each { |g| @ui.say("  gem     #{g}") }
-        gems[:pending].each { |g| @ui.say("  pending #{g} (not installed — run: bundle add #{g})") }
-        gems[:failed].each { |g| @ui.say("  FAILED  #{g} (bundle add failed)") }
+        gem_results.each { |result| print_gems(result) }
         (tailwind[:applied]).each { |i| @ui.say("  tailwind #{i}") }
         tailwind[:manual].each { |m| @ui.say("  manual  #{m}") }
+        print_binstub(binstub)
+      end
+
+      # Each result prints its own group, so the command it tells you to run is
+      # the one that would actually have worked.
+      def print_gems(result)
+        suffix = result[:group] ? " --group #{result[:group]}" : ""
+        result[:applied].each { |g| @ui.say("  gem     #{g}") }
+        result[:pending].each { |g| @ui.say("  pending #{g} (not installed — run: bundle add #{g}#{suffix})") }
+        result[:failed].each { |g| @ui.say("  FAILED  #{g} (bundle add failed)") }
+      end
+
+      def print_binstub(binstub)
+        case binstub[:status]
+        when :written then @ui.say("  create  #{Binstub::PATH}")
+        when :skipped then @ui.say("  skip    #{Binstub::PATH} (already exists)")
+        when :unusable
+          @ui.say("  warn    #{Binstub::PATH} exists but `gem \"#{CLI_GEM}\"` is not in the " \
+                  "Gemfile — it will not run until it is")
+        when :unavailable
+          @ui.say("  manual  #{Binstub::PATH} (add `gem \"#{CLI_GEM}\"` to the Gemfile, then re-run init)")
+        end
       end
     end
   end

data/lib/shadwire/commands/status.rb

@@ -23,8 +23,9 @@ module Shadwire
 
       def call
         project = Project.new(@root)
-        config = Config.load(@root)
+        config, config_error = load_config
         result = context(project, config)
+        result["configError"] = config_error if config_error
 
         begin
           client = RegistryClient.new(@registry_override || config.registry)
@@ -41,6 +42,16 @@ module Shadwire
 
       private
 
+      # A hand-edited shadwire.json must not raise here. The agent skill injects
+      # this command and discards stderr while it chains invocation forms, so a
+      # non-zero exit would reach the agent as "no CLI here" with the real
+      # diagnostic thrown away. Report it and carry on with defaults instead.
+      def load_config
+        [Config.load(@root), nil]
+      rescue Shadwire::Error => e
+        [Config.new(@root, JSON.parse(JSON.generate(Config::DEFAULTS))), e.message]
+      end
+
       def context(project, config)
         {
           "rails" => project.rails?,
@@ -57,6 +68,12 @@ module Shadwire
             "view_component" => project.gem?("view_component"),
             "lucide-rails" => project.gem?("lucide-rails")
           },
+          # The canonical entry point, so the skill can name one invocation
+          # rather than inspecting the Gemfile to guess at one.
+          "cli" => {
+            "gem" => project.gem?("shadwire"),
+            "binstub" => project.binstub?
+          },
           "tailwind" => {
             "css" => config.tailwind_css,
             "importPresent" => tailwind_import?(config)
@@ -120,11 +137,13 @@ module Shadwire
         @ui.say("Stack:      importmap=#{result.dig("stack", "importmap")} " \
                 "stimulus=#{result.dig("stack", "stimulus")} " \
                 "tailwindcss-rails=#{result.dig("stack", "tailwindcssRails")}")
+        @ui.say("CLI:        binstub=#{result.dig("cli", "binstub")} gem=#{result.dig("cli", "gem")}")
         @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("shadwire.json unreadable, using defaults: #{result["configError"]}") if result["configError"]
         @ui.warn("Registry unavailable: #{result["registryError"]}") if result["registryError"]
         return unless result.dig("helpers", "legacyHelperPresent")
 

data/lib/shadwire/dependencies.rb

@@ -28,12 +28,25 @@ module Shadwire
     # 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.
+    # Each result carries its own `group:`, so the recovery command it suggests
+    # matches the one that failed. Collapsing them would tell the user to
+    # `bundle add shadwire`, landing the development-only CLI in the app's
+    # runtime dependencies.
     def self.raise_on_failure!(*results)
-      failed = results.flat_map { |result| Array(result[:failed]) }.uniq
-      return if failed.empty?
+      failing = results.reject { |result| Array(result[:failed]).empty? }
+      return if failing.empty?
 
-      raise Error, "Failed to install: #{failed.join(", ")}. " \
-                   "Run `bundle add #{failed.join(" ")}` in the app and re-run this command."
+      names = failing.flat_map { |result| Array(result[:failed]) }.uniq
+      commands = failing.map { |result| bundle_add_command(result) }
+
+      raise Error, "Failed to install: #{names.join(", ")}. " \
+                   "Run `#{commands.join("` and `")}` in the app and re-run this command."
+    end
+
+    # `bundle add <names...>` for a result, with its group when it has one.
+    def self.bundle_add_command(result)
+      suffix = result[:group] ? " --group #{result[:group]}" : ""
+      "bundle add #{Array(result[:failed]).join(" ")}#{suffix}"
     end
 
     def initialize(project, runner: DEFAULT_RUNNER)
@@ -42,20 +55,26 @@ module Shadwire
     end
 
     # Ensures each gem name is present, running `bundle add <missing...>`.
-    def ensure_gems(names, yes:, confirm: nil)
+    # `group:` adds them to a bundler group — used for the shadwire CLI itself,
+    # which belongs in development, not in the app's runtime dependencies.
+    def ensure_gems(names, yes:, confirm: nil, group: 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)
+      suffix = group ? " --group #{group}" : ""
+      unless apply?(yes, confirm, "Add gems: #{missing.join(", ")} (bundle add#{suffix})")
+        return result(skipped: present, pending: missing, group:)
       end
 
+      command = ["bundle", "add", *missing]
+      command.push("--group", group.to_s) if group
+
       # `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)
+      return result(skipped: present, failed: missing, group:) unless @runner.call(command, chdir: @project.root)
 
-      result(applied: missing, skipped: present)
+      result(applied: missing, skipped: present, group:)
     end
 
     # Ensures each pin ({ "name" =>, "to" => }) exists in config/importmap.rb.
@@ -106,8 +125,8 @@ module Shadwire
 
     private
 
-    def result(applied: [], skipped: [], pending: [], manual: [], failed: [])
-      { applied:, skipped:, pending:, manual:, failed: }
+    def result(applied: [], skipped: [], pending: [], manual: [], failed: [], group: nil)
+      { applied:, skipped:, pending:, manual:, failed:, group: }
     end
 
     def apply?(yes, confirm, description)

data/lib/shadwire/project.rb

@@ -33,6 +33,12 @@ module Shadwire
       gem?("stimulus-rails") || File.exist?(path("app/javascript/controllers/index.js"))
     end
 
+    # The canonical CLI entry point. `status` reports it so the agent skill can
+    # name one invocation instead of guessing from the Gemfile.
+    def binstub?
+      Binstub.exist?(@root)
+    end
+
     def importmap_path
       path("config/importmap.rb")
     end

data/lib/shadwire/version.rb

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

data/lib/shadwire.rb

@@ -2,6 +2,7 @@
 
 require_relative "shadwire/version"
 require_relative "shadwire/errors"
+require_relative "shadwire/binstub"
 require_relative "shadwire/config"
 require_relative "shadwire/project"
 require_relative "shadwire/registry_client"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shadwire
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Eduardo de Moraes
@@ -36,6 +36,7 @@ files:
 - README.md
 - exe/shadwire
 - lib/shadwire.rb
+- lib/shadwire/binstub.rb
 - lib/shadwire/cli.rb
 - lib/shadwire/commands/add.rb
 - lib/shadwire/commands/diff.rb