poetry-ui 0.0.2

data/lib/generators/poetry/block/templates/stepper.html.erb

@@ -0,0 +1,79 @@
+<%# poetry:block title="Stepper" description="A multi-step flow header: numbered step indicators with connectors and completed/current/upcoming states over the current step's panel with back/continue actions." keywords="stepper, wizard, steps, checkout, onboarding, progress, multi-step" %>
+<%# Stepper is a BLOCK, not a component: neither shadcn nor Base UI
+    ships one, so the pattern lives here as copy-in source - adapt the
+    steps freely; nothing hides behind an API. The server owns step state:
+    pass step: as a local, or let it ride ?step= - Back/Continue are plain
+    links that re-render, and completed steps are links back. In a real
+    flow, swap the query param for your wizard's own routes/model state
+    and the final action for a form submit. %>
+<% steps = ["Shipping", "Payment", "Review"] %>
+<% step = (local_assigns[:step] || params[:step] || 2).to_i.clamp(1, steps.length) %>
+<% panels = {
+     1 => ["Shipping", "Step 1 of 3 - where this order lands.",
+           "Address fields mount here; this panel is the step's content slot."],
+     2 => ["Payment", "Step 2 of 3 - how this order gets paid.",
+           "Card details are collected by the payment element that mounts here; this panel is the step's content slot."],
+     3 => ["Review", "Step 3 of 3 - confirm and place the order.",
+           "The order summary renders here - line items, shipping choice, and the charge that Place order will submit."]
+   } %>
+<% title, description, body = panels.fetch(step) %>
+<div class="mx-auto max-w-2xl p-6">
+  <nav aria-label="Progress">
+    <ol class="flex items-center gap-3">
+      <% steps.each_with_index do |label, index| %>
+        <% number = index + 1 %>
+        <% unless number == 1 %>
+          <li aria-hidden="true" class="h-px min-w-8 flex-1 <%= number <= step ? "bg-primary" : "bg-border" %>"></li>
+        <% end %>
+        <% if number < step %>
+          <%# Completed: filled indicator with a check, revisitable. %>
+          <li class="flex items-center">
+            <a href="?step=<%= number %>" class="flex items-center gap-3 rounded-md outline-none focus-visible:ring-2 focus-visible:ring-ring">
+              <span class="flex size-8 items-center justify-center rounded-full bg-primary text-primary-foreground">
+                <%= poetry_icon(name: :check, class: "size-4", label: "Completed") %>
+              </span>
+              <span class="text-sm font-medium"><%= label %></span>
+            </a>
+          </li>
+        <% elsif number == step %>
+          <%# Current: outlined in primary, named by aria-current. %>
+          <li aria-current="step" class="flex items-center gap-3">
+            <span class="flex size-8 items-center justify-center rounded-full border-2 border-primary text-sm font-semibold text-primary"><%= number %></span>
+            <span class="text-sm font-medium"><%= label %></span>
+          </li>
+        <% else %>
+          <%# Upcoming: muted and inert until reached. %>
+          <li class="flex items-center gap-3">
+            <span class="flex size-8 items-center justify-center rounded-full border border-border text-sm text-muted-foreground"><%= number %></span>
+            <span class="text-sm text-muted-foreground"><%= label %></span>
+          </li>
+        <% end %>
+      <% end %>
+    </ol>
+  </nav>
+
+  <div class="mt-6">
+    <%= poetry_card do |card| %>
+      <% card.with_title { title } %>
+      <% card.with_description { description } %>
+      <div class="space-y-4 text-sm">
+        <p><%= body %></p>
+      </div>
+      <% card.with_footer do %>
+        <div class="flex w-full items-center justify-between">
+          <% if step > 1 %>
+            <%= poetry_button(tag: :a, href: "?step=#{step - 1}", variant: :outline) { "Back" } %>
+          <% else %>
+            <span></span>
+          <% end %>
+          <% if step < steps.length %>
+            <%= poetry_button(tag: :a, href: "?step=#{step + 1}") { "Continue to #{steps[step].downcase}" } %>
+          <% else %>
+            <%# The terminal action: wire this to your submit. %>
+            <%= poetry_button { "Place order" } %>
+          <% end %>
+        </div>
+      <% end %>
+    <% end %>
+  </div>
+</div>

data/lib/generators/poetry/block/templates/top_nav.html.erb

@@ -0,0 +1,44 @@
+<%# poetry:block title="Top nav" description="A site navigation bar: brand mark, a products dropdown of rich title-and-description links, direct destinations, and the log-in / sign-up action pair." keywords="navigation, navbar, topbar, site, marketing, links" %>
+<header class="w-full border-b">
+  <div class="mx-auto flex h-14 max-w-5xl items-center justify-between gap-6 px-6">
+    <%= poetry_link(href: "/", underline: :none, class: "inline-flex items-center gap-2 text-sm font-semibold") do %>
+      <%= poetry_icon(name: :"audio-waveform", class: "size-4") %> Meridian
+    <% end %>
+    <%= poetry_navigation_menu(label: "Main", viewport: true) do |nav| %>
+      <% nav.with_item("Products", value: "products") do %>
+        <div class="grid w-96 grid-cols-2 gap-1 p-2">
+          <%= poetry_navigation_menu_link(href: "/products/orders") do %>
+            <div class="space-y-0.5">
+              <div class="text-sm font-medium">Orders</div>
+              <p class="text-xs text-muted-foreground">Fulfillment from checkout to doorstep.</p>
+            </div>
+          <% end %>
+          <%= poetry_navigation_menu_link(href: "/products/customers") do %>
+            <div class="space-y-0.5">
+              <div class="text-sm font-medium">Customers</div>
+              <p class="text-xs text-muted-foreground">Profiles, segments, and lifetime history.</p>
+            </div>
+          <% end %>
+          <%= poetry_navigation_menu_link(href: "/products/analytics") do %>
+            <div class="space-y-0.5">
+              <div class="text-sm font-medium">Analytics</div>
+              <p class="text-xs text-muted-foreground">Live dashboards over every workspace event.</p>
+            </div>
+          <% end %>
+          <%= poetry_navigation_menu_link(href: "/products/automations") do %>
+            <div class="space-y-0.5">
+              <div class="text-sm font-medium">Automations</div>
+              <p class="text-xs text-muted-foreground">Workflows that run while the team sleeps.</p>
+            </div>
+          <% end %>
+        </div>
+      <% end %>
+      <% nav.with_link("Pricing", href: "/pricing") %>
+      <% nav.with_link("Docs", href: "/docs") %>
+    <% end %>
+    <div class="flex items-center gap-2">
+      <%= poetry_button(variant: :ghost, size: :sm, tag: :a, href: "/login") { "Log in" } %>
+      <%= poetry_button(size: :sm, tag: :a, href: "/signup") { "Sign up" } %>
+    </div>
+  </div>
+</header>

data/lib/generators/poetry/diff/diff_generator.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "yaml"
+
+module Poetry
+  # `rails g poetry:diff` - the copy-in upgrade report. poetry's
+  # three ownership tiers upgrade differently: gem-owned code rides
+  # `bundle update`, the vendored css set rides a `poetry:install` re-run,
+  # and copy-ins are app-OWNED - nothing may rewrite them. This generator
+  # closes the loop on that third tier: it reads the provenance
+  # manifest (config/poetry_components.yml) and reports, file by file, where
+  # the app's copies stand against what the installed gems ship NOW.
+  # Read-only by contract - it prints, it never writes; `poetry:add`
+  # re-run is the (skip-if-exists) way to pick up newly-shipped files.
+  #
+  # @example
+  #   bin/rails g poetry:diff
+  class DiffGenerator < Rails::Generators::Base
+    # The copy-in provenance manifest poetry:add records into.
+    MANIFEST = "config/poetry_components.yml"
+    # Where component copy-ins land in the host app.
+    COMPONENT_ROOT = "app/components/poetry/ui"
+    # Where block copy-ins land in the host app.
+    BLOCKS_ROOT = "app/views/blocks"
+    # The ownership header poetry:block stamps on copy (stripped before
+    # comparing, like the gem template's own poetry:block header).
+    BLOCK_HEADER = /\A<%#[^%]*%>\n?/
+
+    desc "Report drift between copied-in poetry components/blocks and what the installed gems ship (read-only)"
+
+    # Step: reports drift for every manifest-recorded component copy-in.
+    # @api private
+    def report_components
+      entries = manifest_components
+      if entries.empty?
+        say "no copy-ins recorded in #{MANIFEST} - nothing to diff"
+      else
+        entries.each { |name, record| report_component(name, record) }
+      end
+    end
+
+    # Step: reports how copied blocks differ from the gem templates.
+    # @api private
+    def report_blocks
+      copied = Dir[File.join(destination_root, BLOCKS_ROOT, "_*.html.erb")]
+      return if copied.empty?
+
+      say "blocks are app-owned starting points - differing from the gem is normal, not drift:"
+      copied.each { |path| report_block(path) }
+    end
+
+    private
+
+    def report_component(name, record)
+      return report_remote(name, record) if record.is_a?(Hash) && record.key?("source")
+
+      version = record.is_a?(Hash) ? record["version"] : nil
+      gem_dir = Poetry::Ui.root.join("app/components/poetry/ui", name)
+      unless gem_dir.directory?
+        say_status :gone, "#{name} - copied at #{version}, no longer shipped by poetry-ui", :yellow
+        return
+      end
+
+      changes = component_changes(name, gem_dir)
+      header = "#{name} - copied at #{version || "unknown"}, gem ships #{Poetry::Ui::VERSION}"
+      if changes.empty?
+        say_status :same, "#{header}: all files match", :green
+      else
+        say_status :drift, header, :yellow
+        changes.each { |line| say "    #{line}" }
+      end
+    end
+
+    # One line per file that is not byte-identical, in gem order, then any
+    # app-local extras. Line counts, not hunks - the report is a pointer,
+    # the diff tool of record is git in the app repo.
+    def component_changes(name, gem_dir)
+      changes = []
+      gem_files = gem_dir.glob("**/*").select(&:file?).sort
+      gem_files.each do |file|
+        relative = file.relative_path_from(gem_dir)
+        app_path = File.join(destination_root, COMPONENT_ROOT, name, relative.to_s)
+        if !File.exist?(app_path)
+          changes << "#{relative}: not copied locally (new upstream file? `bin/rails g poetry:add #{name}` " \
+                     "adds missing files without touching existing ones)"
+        elsif File.read(app_path) != file.read
+          changes << "#{relative}: differs (app #{File.foreach(app_path).count} lines, " \
+                     "gem #{file.each_line.count} lines)"
+        end
+      end
+      app_dir = File.join(destination_root, COMPONENT_ROOT, name)
+      Dir[File.join(app_dir, "**/*")].select { |f| File.file?(f) }.sort.each do |path|
+        relative = path.delete_prefix("#{app_dir}/")
+        changes << "#{relative}: local-only (yours)" unless gem_dir.join(relative).file?
+      end
+      changes
+    end
+
+    def report_remote(name, record)
+      say_status :remote, "#{name} - installed from #{record["source"]}; re-run " \
+                          "`bin/rails g poetry:add #{record["source"]}` to compare (skip-if-exists)", :cyan
+    end
+
+    def report_block(path)
+      name = File.basename(path, ".html.erb").delete_prefix("_").tr("_", "-")
+      entry = block_catalog[name]
+      unless entry
+        say_status :yours, "#{name} - not in the gem catalog (renamed or your own)", :cyan
+        return
+      end
+
+      gem_body = Poetry::Ui.root.join(entry.fetch("template")).read.sub(BLOCK_HEADER, "")
+      app_body = File.read(path).sub(BLOCK_HEADER, "")
+      if app_body == gem_body
+        say_status :same, "#{name} - matches the gem's current template", :green
+      else
+        say_status :edited, "#{name} - differs from the gem's current template " \
+                            "(reference: #{entry.fetch("template")})", :cyan
+      end
+    end
+
+    def manifest_components
+      path = File.join(destination_root, MANIFEST)
+      config = File.exist?(path) ? YAML.safe_load_file(path) : nil
+      config.is_a?(Hash) && config["components"].is_a?(Hash) ? config["components"] : {}
+    end
+
+    def block_catalog
+      @block_catalog ||= YAML.safe_load_file(
+        Poetry::Ui.root.join(Poetry::Core::Registry::RELATIVE_PATH)
+      )["blocks"] || {}
+    end
+  end
+end

data/lib/generators/poetry/editor/editor_generator.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "json"
+require "yaml"
+require "time"
+
+module Poetry
+  # `rails g poetry:editor` - wire the poetry agent surface into the editors a
+  # Rails team actually uses. poetry has no bespoke extension (a possible
+  # future direction); what it DOES have is a standard MCP stdio server and a
+  # source-generated component registry, so this generator emits:
+  #
+  #   .mcp.json            Claude Code   (mcpServers)
+  #   .cursor/mcp.json     Cursor        (mcpServers)
+  #   .vscode/mcp.json     VS Code       (servers + type: stdio)
+  #   .vscode/poetry.code-snippets   one snippet per poetry_* helper, with the
+  #                                   real variant/size enums as tab-stop choices
+  #   .herb.yml            Herb (linter / formatter / language server), unless
+  #                        the app already has one
+  #   .stimulus-lsp/config.json   poetry's controller identifiers for Stimulus LSP
+  #                               (upsert: an existing ignore list keeps its entries)
+  #
+  # The MCP writes are upserts: an existing config keeps its other servers and
+  # gains a `poetry` entry; a config that already has one is left untouched; a
+  # JSONC file poetry can't parse is reported, never clobbered. Editors whose
+  # MCP config is global / IDE-managed (Zed, Windsurf, RubyMine) get a
+  # copy-paste block printed instead.
+  #
+  # @example
+  #   bin/rails g poetry:editor
+  class EditorGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    # Editors whose MCP config is global or IDE-managed, so poetry prints a
+    # paste-block instead of writing a project file.
+    MANUAL_EDITORS = <<~TEXT
+      Zed        settings.json ->
+                 "context_servers": { "poetry": { "command": { "path": "bundle", "args": ["exec", "poetry-agent"] } } }
+      Windsurf   ~/.codeium/windsurf/mcp_config.json ->
+                 { "mcpServers": { "poetry": { "command": "bundle", "args": ["exec", "poetry-agent"] } } }
+      RubyMine   Settings -> Tools -> AI Assistant -> Model Context Protocol (MCP) ->
+                 add a stdio server: command `bundle exec poetry-agent` (or import .mcp.json). RubyMine 2025.2+.
+    TEXT
+
+    # The Herb toolchain (HTML+ERB parser, linter, formatter, language server)
+    # reads one file. Poetry templates are gated to parse AND compile under
+    # Herb (Rails core's ERB engine since 8.2), so a Poetry app can run the
+    # whole toolchain; two linter rules misread ViewComponent slot setters on
+    # helper-yielded builders today, so they start off with the upstream
+    # issues to watch. The version pin keeps a linter upgrade from enabling
+    # rules silently.
+    HERB_CONFIG = <<~YML
+      # Herb toolchain configuration (linter / formatter / language server).
+      # https://herb-tools.dev/configuration - written by `rails g poetry:editor`.
+      version: 0.10.3
+
+      framework: actionview
+
+      linter:
+        enabled: true
+        rules:
+          # `<%= poetry_card do |card| %><% card.with_title(...) %>` is flagged as
+          # a discarded value until marcoroth/herb#2426 lands.
+          erb-no-unused-expressions:
+            enabled: false
+          # `<% item.with_icon { ... } %>` (brace-form slot setters) is flagged and
+          # the autofix renders the wrong thing - marcoroth/herb#2340.
+          actionview-no-silent-helper:
+            enabled: false
+
+      formatter:
+        enabled: false
+    YML
+
+    # Where the Herb language server comes from, per editor.
+    HERB_EDITORS = <<~TEXT
+      VS Code    install the "Herb LSP" extension (marcoroth.herb-lsp); Stimulus LSP (marcoroth.stimulus-lsp)
+                 understands the same HTML+ERB
+      Zed        ships inside the official Ruby extension - nothing to add
+      Neovim     npm install -g @herb-tools/language-server, then lspconfig's herb_ls
+      CI         npx --yes @herb-tools/linter app   (or bundle exec herb lint)
+      Stimulus   .stimulus-lsp/config.json lists poetry's controllers for Stimulus LSP - it checks YOUR
+                 controllers; bin/rails poetry:check validates poetry's (data: keywords included)
+    TEXT
+
+    # Stimulus LSP resolves identifiers from the app's controller directories
+    # and node_modules; controllers a gem serves through importmap are
+    # invisible to it, so every hand-written `poetry--...` descriptor reads
+    # as an invalid controller with a quick-fix that scaffolds a bogus file.
+    # The LSP's one lever is an ignore list of exact identifiers, so poetry
+    # lists every controller its installed gems ship. Those descriptors are
+    # poetry:check's to validate (kwargs included); the LSP keeps yours.
+    STIMULUS_LSP_VERSION = "1.1.2" # the schema's writer version; the LSP rewrites it on its own saves
+
+    # The check hook: stdlib Ruby that runs `poetry check` on the one app
+    # template an agent just edited and feeds the findings back (errors as a
+    # blocking report, warnings as context). Registered for Claude Code and
+    # Cursor; the script filters to app templates itself, since neither
+    # hook's matcher can see a file path.
+    HOOK_SCRIPT = "bin/poetry-check-hook"
+    # The Claude Code entry: PostToolUse on the file-editing tools.
+    CLAUDE_HOOK = { "matcher" => "Edit|Write|MultiEdit",
+                    "hooks" => [{ "type" => "command", "command" => HOOK_SCRIPT, "timeout" => 120 }] }.freeze
+    # Cursor's Write is its file-edit tool type; the payload is read
+    # leniently and the hook stays silent when it finds no path.
+    CURSOR_HOOK = { "command" => HOOK_SCRIPT, "matcher" => "Write", "timeout" => 120 }.freeze
+    # What the generator says about the hook once it is written.
+    HOOK_NOTE = <<~TEXT
+      bin/poetry-check-hook runs poetry check on every app template an agent edits and feeds the
+      findings back: registered in .claude/settings.json (Claude Code, PostToolUse on Edit/Write) and
+      .cursor/hooks.json (Cursor, postToolUse on Write). Claude Code reads hooks at session start -
+      start a new session (or check /hooks) before expecting feedback.
+    TEXT
+
+    desc "Wire poetry's MCP server + component snippets + Herb and Stimulus LSP config + the check hook into " \
+         "your editors (.mcp.json / .cursor/mcp.json / .vscode/mcp.json + .vscode/poetry.code-snippets + " \
+         ".herb.yml + .stimulus-lsp/config.json + bin/poetry-check-hook wired into .claude/settings.json and " \
+         ".cursor/hooks.json)"
+
+    # Step: upserts the poetry server into .mcp.json.
+    # @api private
+    def write_claude_code_config
+      upsert_mcp ".mcp.json", "mcpServers", stdio: false
+    end
+
+    # Step: upserts the poetry server into .cursor/mcp.json.
+    # @api private
+    def write_cursor_config
+      upsert_mcp ".cursor/mcp.json", "mcpServers", stdio: false
+    end
+
+    # Step: upserts the poetry server into .vscode/mcp.json.
+    # @api private
+    def write_vscode_config
+      upsert_mcp ".vscode/mcp.json", "servers", stdio: true
+    end
+
+    # Step: writes one VS Code snippet per poetry_* helper.
+    # @api private
+    def write_snippets
+      create_file ".vscode/poetry.code-snippets", "#{JSON.pretty_generate(snippets)}\n", force: true
+    end
+
+    # Step: writes .herb.yml for the Herb toolchain, unless the app has one.
+    # @api private
+    def write_herb_config
+      if File.exist?(File.join(destination_root, ".herb.yml"))
+        say_status :skip, ".herb.yml exists - keeping yours (poetry's rule notes: /editors on the docs site)",
+                   :yellow
+      else
+        create_file ".herb.yml", HERB_CONFIG
+      end
+    end
+
+    # Step: lists poetry's controller identifiers for Stimulus LSP (upsert).
+    # @api private
+    def write_stimulus_lsp_config
+      upsert_stimulus_lsp ".stimulus-lsp/config.json"
+    end
+
+    # Step: writes the check hook script.
+    # @api private
+    def write_check_hook
+      copy_file "poetry-check-hook", HOOK_SCRIPT
+      chmod HOOK_SCRIPT, 0o755
+    end
+
+    # Step: registers the hook for Claude Code (upsert into .claude/settings.json).
+    # @api private
+    def write_claude_code_hook
+      upsert_hook ".claude/settings.json", "PostToolUse", CLAUDE_HOOK
+    end
+
+    # Step: registers the hook for Cursor (upsert into .cursor/hooks.json).
+    # @api private
+    def write_cursor_hook
+      upsert_hook ".cursor/hooks.json", "postToolUse", CURSOR_HOOK, seed: { "version" => 1 }
+    end
+
+    # Step: explains the check hook and when each editor picks it up.
+    # @api private
+    def announce_check_hook
+      say "\npoetry:editor - the check hook:", :green
+      say HOOK_NOTE
+    end
+
+    # Step: prints the paste-blocks for IDE-managed MCP configs.
+    # @api private
+    def announce_manual_editors
+      say "\npoetry:editor - editors with global / IDE-managed MCP config (paste-blocks):", :green
+      say MANUAL_EDITORS
+      say "\npoetry:editor - Herb (HTML+ERB linter + language server), configured by .herb.yml:", :green
+      say HERB_EDITORS
+      say "Full setup + a per-editor matrix: /editors on the docs site.\n"
+    end
+
+    private
+
+    # The stdio server every host launches the same way. Zero config beyond the
+    # bundle exec line; the agent auto-locates the gem and reads the committed
+    # registry (boot-free).
+    def server_entry(stdio:)
+      entry = { "command" => "bundle", "args" => %w[exec poetry-agent] }
+      stdio ? { "type" => "stdio" }.merge(entry) : entry
+    end
+
+    def upsert_mcp(relative, key, stdio:)
+      path = File.join(destination_root, relative)
+      unless File.exist?(path)
+        create_file relative, "#{JSON.pretty_generate(key => { "poetry" => server_entry(stdio: stdio) })}\n"
+        return
+      end
+
+      data = parse_json(File.read(path))
+      return say_status(:skip, "#{relative} isn't plain JSON (JSONC?) - add the poetry server by hand", :yellow) \
+        if data.nil?
+
+      servers = (data[key] ||= {})
+      return say_status(:identical, relative, :blue) if servers["poetry"]
+
+      servers["poetry"] = server_entry(stdio: stdio)
+      File.write(path, "#{JSON.pretty_generate(data)}\n")
+      say_status :update, "#{relative} (added the poetry server)", :green
+    end
+
+    # Upserts one hook entry under hooks.<event>: a file already naming the
+    # script anywhere in that list is identical, other hooks and keys are
+    # kept, a JSONC file is reported and never clobbered.
+    def upsert_hook(relative, event, entry, seed: {})
+      path = File.join(destination_root, relative)
+      unless File.exist?(path)
+        create_file relative, "#{JSON.pretty_generate(seed.merge("hooks" => { event => [entry] }))}\n"
+        return
+      end
+
+      data = parse_json(File.read(path))
+      if data.nil?
+        return say_status(:skip, "#{relative} isn't plain JSON (JSONC?) - add the poetry hook by hand",
+                          :yellow)
+      end
+
+      hooks = (data["hooks"] ||= {})
+      entries = hooks.is_a?(Hash) ? (hooks[event] ||= []) : nil
+      unless entries.is_a?(Array)
+        return say_status(:skip, "#{relative} has an unexpected hooks shape - add the poetry hook by hand", :yellow)
+      end
+      return say_status(:identical, relative, :blue) if JSON.generate(entries).include?(HOOK_SCRIPT)
+
+      entries << entry
+      File.write(path, "#{JSON.pretty_generate(data)}\n")
+      say_status :update, "#{relative} (added the poetry check hook)", :green
+    end
+
+    # Every poetry-owned identifier the installed gems ship (core + any
+    # registered manifest), sorted for a stable file.
+    def poetry_identifiers
+      Poetry::Core::Stimulus::Manifest.catalog.keys.sort
+    end
+
+    def upsert_stimulus_lsp(relative)
+      path = File.join(destination_root, relative)
+      identifiers = poetry_identifiers
+      unless File.exist?(path)
+        create_file relative, "#{JSON.pretty_generate(stimulus_lsp_config(identifiers))}\n"
+        return
+      end
+
+      data = parse_json(File.read(path))
+      return say_status(:skip, "#{relative} isn't plain JSON - add poetry's identifiers by hand", :yellow) if data.nil?
+
+      options = (data["options"] ||= {})
+      ignored = Array(options["ignoredControllerIdentifiers"])
+      missing = identifiers - ignored
+      return say_status(:identical, relative, :blue) if missing.empty?
+
+      options["ignoredControllerIdentifiers"] = (ignored + missing).uniq.sort
+      options["ignoredAttributes"] = Array(options["ignoredAttributes"])
+      data["updatedAt"] = Time.now.utc.iso8601
+      File.write(path, "#{JSON.pretty_generate(data)}\n")
+      say_status :update, "#{relative} (+#{missing.size} poetry controller identifiers)", :green
+    end
+
+    def stimulus_lsp_config(identifiers)
+      now = Time.now.utc.iso8601
+      { "version" => STIMULUS_LSP_VERSION, "createdAt" => now, "updatedAt" => now,
+        "options" => { "ignoredControllerIdentifiers" => identifiers, "ignoredAttributes" => [] } }
+    end
+
+    # nil for anything we can't safely round-trip. JSONC comments are detected
+    # BEFORE parsing: some json versions silently accept `//`/`/* */` and would
+    # then drop the comments on re-serialize - poetry never clobbers a config it
+    # can't preserve.
+    def parse_json(text)
+      return nil if text.match?(%r{^\s*//}) || text.include?("/*")
+
+      JSON.parse(text)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # One snippet per main component helper (poetry_<name>), driven by the
+    # committed registry so it never drifts from the shipped catalog. A block
+    # form for components that compose via slots; inline for atoms. The primary
+    # enum (variant, else the first declared one) becomes a choice tab-stop, so
+    # the completion only offers values that actually exist.
+    def snippets
+      registry = YAML.safe_load_file(Poetry::Ui.root.join("config/component_registry.yml"))
+      registry.fetch("components").keys.sort.to_h do |path|
+        name = path.delete_prefix("poetry/ui/").tr("/", "_")
+        component = registry.fetch("components").fetch(path)
+        [
+          "poetry #{name.tr("_", " ")}",
+          { "prefix" => "poetry_#{name}", "scope" => "erb",
+            "body" => snippet_body(name, component), "description" => "poetry #{humanize(name)} component" }
+        ]
+      end
+    end
+
+    def snippet_body(name, component)
+      call = "poetry_#{name}#{enum_argument(component)}"
+      if Array(component["slots"]).any?
+        ["<%= #{call} do |c| %>", "\t$0", "<% end %>"]
+      else
+        "<%= #{call} %>$0"
+      end
+    end
+
+    # `(variant: :${1|a,b,c|})` for the primary enum, or "" when the component
+    # declares none. Enums come from BOTH the styles DSL (variant/size) and
+    # options (tag/orientation/...); a declared `variant` wins.
+    def enum_argument(component)
+      enums = (Array(component["styles"]) + Array(component["options"])).select { |o| o["variants"] }
+      chosen = enums.find { |o| o["name"] == "variant" } || enums.first
+      return "" unless chosen
+
+      "(#{chosen["name"]}: :${1|#{Array(chosen["variants"]).join(",")}|})"
+    end
+
+    def humanize(name)
+      name.split("_").map(&:capitalize).join(" ")
+    end
+  end
+end