shadwire 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1cdc0f4830063d6e21c79acbe20a20d3b81862ff346a3af2fff6888af18ba8c2
+  data.tar.gz: a455411bae400e6e0a99f4ad693988add8b95945abf15081321631f5922e3124
+SHA512:
+  metadata.gz: 4ae1610e1fc2382eba1787a94ba27be6efaed66ed8535bbd72a64a09b82aa79df01271ad9186330e9fbefebe3487f84f447f662472bab4292de552d43e950b76
+  data.tar.gz: a10682b3ba15a5e955b0952967b5af2695d040b5f71d08f4dad3d9f9c70bb8f43b146a783081fe1e843646011a66ef8edf35821eab39ccb3a28ca270fb2fa01d

data/README.md

@@ -0,0 +1,116 @@
+# shadwire
+
+shadcn/ui components for Ruby on Rails, delivered the shadcn **Open Code** way:
+the CLI copies component *source* into your app and records it in `shadwire.json`.
+Installed files are yours to edit — there is no runtime dependency on Shadwire.
+
+Part of the [Shadwire](https://github.com/edumoraes/shadwire) monorepo. The
+component source lives in that repo's `registry/` and is published to a static
+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
+```
+
+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.
+
+| 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` |
+| `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` |
+| `info NAME` | Show a component's metadata: files, gems, importmap pins, registry dependencies. | `--registry URL`, `--json` |
+| `diff [NAME...]` | Show how installed files have drifted from the registry (`unchanged` / `modified` / `missing`). | `--registry URL`, `--json`, `--exit-code` |
+| `update [NAME...]` | Re-apply the registry version of installed components (all, or the named ones). | `--yes`, `--overwrite`, `--no-deps`, `--registry URL`, `--json` |
+| `remove NAME...` | Uninstall components, deleting only their own files (never the shared base, never files still used by another component). | `--yes`, `--registry URL`, `--json` |
+| `status` | Report app context: stack detection, installed components with the helpers they define, and drift. | `--registry URL`, `--json` |
+| `version` | Print the installed CLI version. | — |
+
+### `status` and coding agents
+
+`status --json` is the one call that describes the whole install, which is why
+the Shadwire agent skill injects it:
+
+```json
+{
+  "rails": true, "configPresent": true, "registryVersion": "0.2.0",
+  "stack": { "importmap": true, "stimulus": true, "tailwindcssRails": true },
+  "helpers": { "includeAllHelpers": true, "legacyHelperPresent": false },
+  "installed": [
+    { "name": "card", "drift": "unchanged",
+      "helpers": ["ui_card", "ui_card_header", "ui_card_title"],
+      "classes": ["Ui::CardComponent", "Ui::Card::HeaderComponent"] }
+  ],
+  "availableCount": 58
+}
+```
+
+`installed[].helpers` lists the `ui_*` methods that actually exist in the app, so
+there is no guessing about which helpers are callable.
+
+`status` never raises: a directory that is not a Rails app, a missing
+`shadwire.json`, and an unreachable registry are all reported as fields
+(`"rails": false`, `"registryError": "..."`) with exit code 0.
+
+### Flags
+
+- `--cwd DIR` — run against another app directory (default: the current directory). Available on every command.
+- `--yes`, `-y` — apply file and dependency changes without prompting (the agent / CI path).
+- `--overwrite` — overwrite locally-modified files without prompting (`add` / `update`).
+- `--no-deps` — skip transitive registry dependencies (`add` / `update`; deps are on by default).
+- `--registry URL` — install or read from this registry instead of the configured one.
+- `--json` — emit machine-readable JSON instead of human output.
+- `--force` — overwrite an existing `shadwire.json` (`init`).
+- `--exit-code` — make `diff` exit non-zero when any drift is found (for CI).
+
+## `shadwire.json`
+
+`init` writes `shadwire.json` at the app root. It records the registry, where
+files install (aliases), the Tailwind entrypoint, and what is installed:
+
+```json
+{
+  "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"] }
+  }
+}
+```
+
+- `registry` — base URL the CLI installs from (persisted from `init --registry`).
+- `tailwind.css` — the app's Tailwind entrypoint that receives the `@import`.
+- `aliases` — install targets for each kind of file.
+- `installed` — per-component `version` plus the files it owns (used by `diff`, `update`, and `remove`).
+
+## Registry resolution
+
+For any command, the registry base URL is resolved in this order:
+
+1. the `--registry` flag, if given;
+2. the `registry` field in the app's `shadwire.json`;
+3. the built-in default, `https://edumoraes.github.io/shadwire/r`.
+
+Both `https://` and local `file://` bases are supported. Point `--registry` at a
+`file://` path to install from a registry built locally with `bin/build_registry`
+(for example `file://$PWD/build/r`). The CLI reads `index.json` (the catalog and
+shared base) and `<name>.json` (a component with its files inlined) from that base.
+
+## License
+
+MIT.

data/exe/shadwire

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "shadwire"
+
+Shadwire::CLI.start(ARGV)

data/lib/shadwire/cli.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Shadwire
+  class CLI < Thor
+    package_name "shadwire"
+
+    def self.exit_on_failure? = true
+
+    class_option :cwd, type: :string,
+                       desc: "Run against this app directory (default: current directory)"
+
+    desc "version", "Print the shadwire version"
+    def version
+      puts Shadwire::VERSION
+    end
+
+    desc "init", "Bootstrap shadwire in a Rails app (config, base files, base deps)"
+    method_option :yes, type: :boolean, default: false, aliases: "-y",
+                        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"
+    method_option :json, type: :boolean, default: false, desc: "Emit machine-readable JSON"
+    def init
+      run_command do |root, ui|
+        Commands::Init.new(
+          root:, registry: options[:registry], yes: options[:yes],
+          force: options[:force], json: options[:json], ui:
+        ).call
+      end
+    end
+
+    desc "add NAME...", "Install components and their registry dependencies"
+    method_option :yes, type: :boolean, default: false, aliases: "-y",
+                        desc: "Apply file/dependency changes without prompting"
+    method_option :overwrite, type: :boolean, default: false,
+                              desc: "Overwrite locally-modified files without prompting"
+    method_option :deps, type: :boolean, default: true,
+                         desc: "Install transitive registry dependencies (--no-deps to skip)"
+    method_option :registry, type: :string, desc: "Registry base URL to install from"
+    method_option :json, type: :boolean, default: false, desc: "Emit machine-readable JSON"
+    def add(*names)
+      run_command do |root, ui|
+        raise Shadwire::Error, "add requires at least one component name" if names.empty?
+
+        Commands::Add.new(
+          root:, names:, yes: options[:yes], overwrite: options[:overwrite],
+          no_deps: !options[:deps], registry: options[:registry], json: options[:json], ui:
+        ).call
+      end
+    end
+
+    desc "list", "List every component in the registry catalog"
+    method_option :registry, type: :string, desc: "Registry base URL to read from"
+    method_option :json, type: :boolean, default: false, desc: "Emit machine-readable JSON"
+    def list
+      run_command do |root, ui|
+        Commands::List.new(root:, registry: options[:registry], json: options[:json], ui:).call
+      end
+    end
+
+    desc "search QUERY", "Search the catalog by name, title, or description"
+    method_option :registry, type: :string, desc: "Registry base URL to read from"
+    method_option :json, type: :boolean, default: false, desc: "Emit machine-readable JSON"
+    def search(query = nil)
+      run_command do |root, ui|
+        raise Shadwire::Error, "search requires a query" if query.nil? || query.strip.empty?
+
+        Commands::Search.new(root:, query:, registry: options[:registry], json: options[:json], ui:).call
+      end
+    end
+
+    desc "info NAME", "Show a component's metadata (files, gems, pins, dependencies)"
+    method_option :registry, type: :string, desc: "Registry base URL to read from"
+    method_option :json, type: :boolean, default: false, desc: "Emit machine-readable JSON"
+    def info(name)
+      run_command do |root, ui|
+        Commands::Info.new(root:, name:, registry: options[:registry], json: options[:json], ui:).call
+      end
+    end
+
+    desc "diff [NAME...]", "Show how installed files have drifted from the registry"
+    method_option :registry, type: :string, desc: "Registry base URL to compare against"
+    method_option :json, type: :boolean, default: false, desc: "Emit machine-readable JSON"
+    method_option :exit_code, type: :boolean, default: false,
+                              desc: "Exit non-zero when drift is found (for CI)"
+    def diff(*names)
+      run_command do |root, ui|
+        result = Commands::Diff.new(
+          root:, names:, registry: options[:registry], json: options[:json], ui:
+        ).call
+        exit 1 if options[:exit_code] && result[:drifted]
+      end
+    end
+
+    desc "update [NAME...]", "Re-apply the registry version of installed components"
+    method_option :yes, type: :boolean, default: false, aliases: "-y",
+                        desc: "Overwrite locally-modified files without prompting"
+    method_option :overwrite, type: :boolean, default: false,
+                              desc: "Overwrite locally-modified files without prompting"
+    method_option :deps, type: :boolean, default: true,
+                         desc: "Also update transitive registry dependencies (--no-deps to skip)"
+    method_option :registry, type: :string, desc: "Registry base URL to update from"
+    method_option :json, type: :boolean, default: false, desc: "Emit machine-readable JSON"
+    def update(*names)
+      run_command do |root, ui|
+        Commands::Update.new(
+          root:, names:, yes: options[:yes], overwrite: options[:overwrite],
+          no_deps: !options[:deps], registry: options[:registry], json: options[:json], ui:
+        ).call
+      end
+    end
+
+    desc "remove NAME...", "Uninstall components, deleting only their own files"
+    method_option :yes, type: :boolean, default: false, aliases: "-y",
+                        desc: "Delete without prompting"
+    method_option :registry, type: :string, desc: "Registry base URL to reconcile against"
+    method_option :json, type: :boolean, default: false, desc: "Emit machine-readable JSON"
+    def remove(*names)
+      run_command do |root, ui|
+        raise Shadwire::Error, "remove requires at least one component name" if names.empty?
+
+        Commands::Remove.new(
+          root:, names:, yes: options[:yes], registry: options[:registry], json: options[:json], ui:
+        ).call
+      end
+    end
+
+    desc "status", "Report app context: stack, installed components, helpers, drift"
+    method_option :registry, type: :string, desc: "Registry base URL to reconcile against"
+    method_option :json, type: :boolean, default: false, desc: "Emit machine-readable JSON"
+    def status
+      run_command do |root, ui|
+        Commands::Status.new(root:, registry: options[:registry], json: options[:json], ui:).call
+      end
+    end
+
+    private
+
+    def resolve_root
+      File.expand_path(options[:cwd] || Dir.pwd)
+    end
+
+    def run_command
+      ui = UI.new(yes: options[:yes])
+      yield(resolve_root, ui)
+    rescue Shadwire::Error => e
+      ui.error(e.message)
+      exit 1
+    rescue Errno::EACCES, Errno::ENOENT, Errno::EROFS => e
+      # Filesystem problems in the consuming app: a read-only checkout, a
+      # deleted directory. Actionable as a sentence, not as a backtrace.
+      ui.error("Filesystem error: #{e.message}")
+      exit 1
+    rescue Interrupt
+      ui.error("Interrupted.")
+      exit 130
+    end
+  end
+end

data/lib/shadwire/commands/add.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Shadwire
+  module Commands
+    # Installs one or more components and their transitive registry
+    # dependencies: writes files (overwrite policy from flags, content-aware
+    # prompting), applies the union of gems + importmap pins, and records each
+    # named component in shadwire.json.
+    class Add
+      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)
+
+        items = resolve_items(client)
+        files = items.flat_map { |item| item.fetch("files") }
+        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, items)
+        config.save
+
+        result = { report:, gems:, pins: }
+        emit(result)
+        Dependencies.raise_on_failure!(gems, pins)
+
+        result
+      end
+
+      private
+
+      def resolve_items(client)
+        @no_deps ? @names.map { |name| client.item(name) } : Resolver.expand(@names, client)
+      end
+
+      def union(items, key)
+        items.flat_map { |item| Array(item[key]) }.uniq
+      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 record_installed(config, client, items)
+        by_name = items.to_h { |item| [item["name"], item] }
+        version = client.index["version"]
+        @names.each do |name|
+          item = by_name[name] || client.item(name)
+          targets = item.fetch("files").map { |file| file["target"] }
+          config.record_installed(name, version, targets)
+        end
+      end
+
+      def emit(result)
+        return @ui.say(JSON.generate(json_payload(result))) if @json
+
+        print_summary(result[:report], result[:gems], result[:pins])
+      end
+
+      def json_payload(result)
+        {
+          "added" => @names,
+          "written" => result[:report][:written],
+          "skipped" => result[:report][:skipped],
+          "gems" => slice_deps(result[:gems]),
+          "pins" => slice_deps(result[:pins])
+        }
+      end
+
+      def slice_deps(deps)
+        { "applied" => deps[:applied], "pending" => deps[:pending],
+          "failed" => deps[:failed], "manual" => deps[:manual] }
+      end
+
+      def print_summary(report, gems, pins)
+        @ui.say("Added #{@names.join(", ")}.")
+        report[:written].each { |t| @ui.say("  write   #{t}") }
+        report[:skipped].each { |t| @ui.say("  skip    #{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)") }
+        pins[:applied].each { |p| @ui.say("  pin     #{p}") }
+        pins[:pending].each { |p| @ui.say("  pending pin #{p}") }
+        (gems[:manual] + pins[:manual]).each { |m| @ui.say("  manual  #{m}") }
+      end
+    end
+  end
+end

data/lib/shadwire/commands/diff.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Shadwire
+  module Commands
+    # Reports how installed files have drifted from the registry: for each file
+    # of each requested (or, with no names, every installed) item, compares the
+    # local bytes to the freshly fetched registry content. Status per file is
+    # "unchanged", "modified", or "missing". Read-only — never writes.
+    class Diff
+      def initialize(root:, names: [], registry: nil, json: false, ui: UI.new)
+        @root = root.to_s
+        @names = names
+        @registry_override = registry
+        @json = json
+        @ui = ui
+      end
+
+      def call
+        config = Config.load(@root)
+        client = RegistryClient.new(@registry_override || config.registry)
+
+        entries = []
+        diffs = {}
+        resolve_names(config).each do |name|
+          client.item(name).fetch("files").each do |file|
+            target = file["target"]
+            status, rendered = compare(target, file["content"])
+            entries << { name:, file: target, status: }
+            diffs["#{name}:#{target}"] = rendered if status == "modified"
+          end
+        end
+
+        drifted = entries.any? { |entry| entry[:status] != "unchanged" }
+        emit(entries, diffs)
+        { entries:, diffs:, drifted: }
+      end
+
+      private
+
+      def resolve_names(config)
+        names = @names.empty? ? config.installed.keys : @names
+        names.each do |name|
+          raise Shadwire::Error, "#{name} is not installed" unless config.installed.key?(name)
+        end
+        names
+      end
+
+      def compare(target, registry_content)
+        path = File.join(@root, target)
+        return ["missing", nil] unless File.exist?(path)
+
+        local = File.read(path)
+        return ["unchanged", nil] if local == registry_content
+
+        ["modified", Differ.unified(local, registry_content, path: target)]
+      end
+
+      def emit(entries, diffs)
+        return @ui.say(JSON.generate(entries)) if @json
+
+        entries.each { |entry| @ui.say("#{entry[:status].ljust(9)} #{entry[:name]}  #{entry[:file]}") }
+        diffs.each_value { |rendered| @ui.say(rendered) if rendered && !rendered.empty? }
+      end
+    end
+  end
+end

data/lib/shadwire/commands/info.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Shadwire
+  module Commands
+    # Shows one item's metadata: type, title, description, file targets, gems,
+    # importmap pins, and registry dependencies. Read-only. The file bodies
+    # (`content`) are stripped so both the JSON and human output stay a manifest,
+    # not a payload. An unknown name propagates RegistryError from the client.
+    class Info
+      def initialize(root:, name:, registry: nil, json: false, ui: UI.new)
+        @root = root.to_s
+        @name = name
+        @registry_override = registry
+        @json = json
+        @ui = ui
+      end
+
+      def call
+        client = RegistryClient.new(@registry_override || Config.load(@root).registry)
+        payload = strip_content(client.item(@name))
+        emit(payload)
+        payload
+      end
+
+      private
+
+      def strip_content(item)
+        payload = item.dup
+        payload["files"] = Array(item["files"]).map { |file| file.reject { |key, _| key == "content" } }
+        payload
+      end
+
+      def emit(payload)
+        return @ui.say(JSON.generate(payload)) if @json
+
+        human(payload)
+      end
+
+      def human(payload)
+        @ui.say("#{payload["name"]} (#{payload["type"]}) — #{payload["title"]}")
+        @ui.say(payload["description"]) if payload["description"]
+        @ui.say("When to use: #{payload["whenToUse"]}") if payload["whenToUse"]
+
+        components(payload)
+
+        @ui.say("Files:")
+        payload["files"].each { |file| @ui.say("  #{file["target"]}") }
+
+        section("Gems", payload["gems"])
+        section("Registry dependencies", payload["registryDependencies"])
+        @ui.say("Requires Stimulus: yes (needs importmap with eager loading)") if payload["requiresStimulus"]
+
+        pins = Array(payload["importmap"])
+        unless pins.empty?
+          @ui.say("Importmap:")
+          pins.each { |pin| @ui.say("  #{pin["name"]} → #{pin["to"]}") }
+        end
+
+        usage(payload)
+      end
+
+      # The generated API: what to call and what it accepts. Roots first, so the
+      # entry point is obvious before its composition parts.
+      def components(payload)
+        entries = Array(payload.dig("api", "components")).reject { |entry| entry["helper"].nil? }
+        return if entries.empty?
+
+        @ui.say("Components:")
+        entries.sort_by { |entry| entry["root"] ? 0 : 1 }.each do |entry|
+          @ui.say("  #{entry["class"]} — #{entry["helper"]}")
+          @ui.say("    variants: #{entry["variants"].join(" | ")}") if entry["variants"]&.any?
+          @ui.say("    sizes:    #{entry["sizes"].join(" | ")}") if entry["sizes"]&.any?
+          props = Array(entry["props"]).map { |prop| prop["default"] ? "#{prop["name"]}: #{prop["default"]}" : "#{prop["name"]}:" }
+          @ui.say("    props:    #{props.join(", ")}") unless props.empty?
+        end
+      end
+
+      def usage(payload)
+        snippets = Array(payload["usage"])
+        return if snippets.empty?
+
+        @ui.say("Usage:")
+        snippets.each { |snippet| @ui.say(snippet.lines.map { |line| "  #{line}" }.join.chomp) }
+      end
+
+      def section(label, values)
+        values = Array(values)
+        @ui.say("#{label}: #{values.join(", ")}") unless values.empty?
+      end
+    end
+  end
+end

data/lib/shadwire/commands/init.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Shadwire
+  module Commands
+    # Bootstraps a consuming Rails app: writes shadwire.json, installs the base
+    # 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
+      def initialize(root:, registry: nil, yes: false, force: false, json: false,
+                     ui: UI.new(yes:), runner: Dependencies::DEFAULT_RUNNER)
+        @root = root.to_s
+        @registry_override = registry
+        @yes = yes
+        @force = force
+        @json = json
+        @ui = ui
+        @runner = runner
+      end
+
+      def call
+        project = Project.new(@root)
+        project.raise_unless_rails!
+
+        config = build_config
+        client = RegistryClient.new(config.registry)
+        base = client.index.fetch("base")
+
+        report = Installer.new(@root, overwrite: :always).install(base.fetch("files"))
+
+        deps = Dependencies.new(project, runner: @runner)
+        confirm = ->(desc) { @ui.confirm?(desc) }
+        gems = deps.ensure_gems(Array(base["gems"]), yes: @yes, confirm:)
+        tailwind = deps.ensure_tailwind_import(
+          vendor_css_target(config, base), css_entry: config.tailwind_css, yes: @yes, confirm:
+        )
+
+        config.save
+        warn_missing_stack(project)
+        result = { config:, report:, gems:, tailwind: }
+        emit(result)
+        Dependencies.raise_on_failure!(gems)
+
+        result
+      end
+
+      private
+
+      def build_config
+        path = File.join(@root, Config::CONFIG_FILE)
+        File.delete(path) if @force && File.exist?(path)
+        config = Config.load(@root)
+        config.registry = @registry_override if @registry_override
+        config
+      end
+
+      def vendor_css_target(config, base)
+        File.join(config.aliases.fetch("vendorCss", "vendor/shadwire"), base.dig("tailwind", "css"))
+      end
+
+      def warn_missing_stack(project)
+        unless project.importmap?
+          @ui.warn("Warning: importmap-rails not detected — Stimulus controllers won't auto-register.")
+        end
+        unless project.stimulus?
+          @ui.warn("Warning: stimulus-rails not detected — interactive components need Stimulus.")
+        end
+        unless project.tailwindcss_rails?
+          @ui.warn("Warning: tailwindcss-rails not detected — add the Shadwire @import to your CSS manually.")
+        end
+      end
+
+      def emit(result)
+        return @ui.say(JSON.generate(json_payload(result))) if @json
+
+        print_summary(result[:report], result[:gems], result[:tailwind])
+      end
+
+      def json_payload(result)
+        {
+          "created" => result[:report][:written],
+          "gems" => { "applied" => result[:gems][:applied], "pending" => result[:gems][:pending],
+                      "failed" => result[:gems][:failed] },
+          "tailwind" => { "applied" => result[:tailwind][:applied], "manual" => result[:tailwind][:manual] },
+          "registry" => result[:config].registry
+        }
+      end
+
+      def print_summary(report, gems, tailwind)
+        @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)") }
+        (tailwind[:applied]).each { |i| @ui.say("  tailwind #{i}") }
+        tailwind[:manual].each { |m| @ui.say("  manual  #{m}") }
+      end
+    end
+  end
+end