CLI

A ferramenta de desenvolvimento que copia o código dos componentes para o seu app e ajuda a mantê-lo em dia com o registry.

Depois do init, rode todos os comandos por bin/shadwire. O binstub carrega a CLI pelo bundle do app, então todo mundo no projeto usa a mesma versão. bin/shadwire help COMANDO mostra a ajuda de um comando.

bin/shadwire status --json        # the project's context
bin/shadwire search <term>       # find a component
bin/shadwire info <name> --json   # its full API
bin/shadwire add <name> --yes     # install it, dependencies included
bin/shadwire list                 # the whole catalog
bin/shadwire diff [name]          # local drift
bin/shadwire diff --exit-code     # non-zero if there is drift (CI)
bin/shadwire update [name] --yes  # reapply the registry (overwrites!)

bin/shadwire status --json        # the project's context
bin/shadwire search <term>       # find a component
bin/shadwire info <name> --json   # its full API
bin/shadwire add <name> --yes     # install it, dependencies included
bin/shadwire list                 # the whole catalog
bin/shadwire diff [name]          # local drift
bin/shadwire diff --exit-code     # non-zero if there is drift (CI)
bin/shadwire update [name] --yes  # reapply the registry (overwrites!)
bin/shadwire remove <name> --yes  # uninstall

Comandos

Comando	O que faz
`shadwire init`	Prepara o app: escreve o shadwire.json, instala os arquivos base compartilhados (ui_component.rb, shadwire.css) e as gems base, adiciona o shadwire ao grupo development, cria o binstub bin/shadwire e insere o @import do Tailwind.
`bin/shadwire add NOME...`	Instala um ou mais componentes junto com os itens do registry de que eles dependem, adiciona gems e pins de importmap e registra tudo no shadwire.json.
`bin/shadwire list`	Lista todos os componentes do catálogo do registry.
`bin/shadwire search CONSULTA`	Busca no catálogo por nome, título, descrição e pelo texto de quando usar, então dá para buscar por coisas como form, modal ou loading.
`bin/shadwire info NOME`	Mostra a API completa do componente: helpers, variantes, tamanhos, props, arquivos, gems, pins e dependências de registry.
`bin/shadwire diff [NOME...]`	Compara os arquivos instalados com o registry e marca cada um como unchanged, modified ou missing, com o diff unificado dos modificados. Não altera nada.
`bin/shadwire update [NOME...]`	Reaplica a versão do registry dos componentes instalados. Sobrescreve edições locais, então rode o diff antes.
`bin/shadwire remove NOME...`	Desinstala componentes. Apaga só os arquivos deles, nunca os arquivos base compartilhados nem um arquivo que outro componente instalado ainda usa.
`bin/shadwire status`	Descreve o app inteiro em uma chamada: a stack detectada, os componentes instalados com os helpers que eles definem, e o que mudou em relação ao registry.
`bin/shadwire version`	Imprime a versão instalada da CLI.

Referência

status

Descreve o projeto em uma única chamada. Rode este primeiro. Também é o único comando que um agente precisa ter no contexto.

bin/shadwire status --json

{
  "rails": true,
  "configPresent": true,
  "registryVersion": "0.2.0",
  "stack": { "importmap": true, "stimulus": true, "tailwindcssRails": true },
  "gems": { "view_component": true, "lucide-rails": true },
  "cli": { "gem": true, "binstub": true },
  "tailwind": { "css": "app/assets/tailwind/application.css", "importPresent": true },

{
  "rails": true,
  "configPresent": true,
  "registryVersion": "0.2.0",
  "stack": { "importmap": true, "stimulus": true, "tailwindcssRails": true },
  "gems": { "view_component": true, "lucide-rails": true },
  "cli": { "gem": true, "binstub": true },
  "tailwind": { "css": "app/assets/tailwind/application.css", "importPresent": true },
  "helpers": { "includeAllHelpers": true, "legacyHelperPresent": false },
  "installed": [
    {
      "name": "card",
      "version": "0.2.0",
      "drift": "unchanged",
      "helpers": ["ui_card", "ui_card_header", "ui_card_title"],
      "classes": ["Ui::CardComponent", "Ui::Card::HeaderComponent"]
    }
  ],
  "availableCount": 58
}

Campo	Leitura
`installed[].helpers`	Os métodos ui_* definidos neste app. Chamar o helper de um componente que não está instalado levanta NoMethodError.
`installed[].drift`	`unchanged`, `modified`, `missing` ou `unknown`.
`stack.importmap`	Se importmap e Stimulus estão presentes. Os componentes interativos dependem dos dois.
`cli.binstub`	Se `bin/shadwire` já existe. Se for falso, rode o `init`.
`helpers.includeAllHelpers`	Falso quer dizer que o app desativou a inclusão automática de helpers do Rails, então cada controller precisa de uma chamada a `helper` para os módulos `Ui::*Helper`.
`helpers.legacyHelperPresent`	Um `app/helpers/ui_helper.rb` que sobrou de antes de os helpers serem separados por componente. Ele define helpers de componentes que você não instalou, e pode ser apagado.

search

A busca olha o nome, o título, a descrição e o texto de quando usar, então dá para buscar pelo que você precisa: form, modal, overlay, loading, right-click.

bin/shadwire search form
bin/shadwire search modal --json

info

A API completa do componente. Consulte antes de escrever ERB, para não ter que adivinhar argumentos. Retorna whenToUse, snippets de usage, requiresStimulus, registryDependencies, os arquivos de instalação e api.components[] com helper, variantes, tamanhos, props e atributos de cada classe.

bin/shadwire info dialog --json

helper vem null para o que não tem wrapper ui_*: a superclasse base, as partes internas que o componente pai renderiza por conta própria e os blocks. O conteúdo dos arquivos fica de fora.

add

bin/shadwire add button dialog --yes

Sem --yes, os arquivos iguais aos do registry são pulados, e a CLI pergunta sobre os que você alterou. Num shell não interativo sem --yes, tudo é pulado e nada é instalado.

diff

Não altera nada. Marca cada arquivo como unchanged, modified ou missing, com o diff unificado dos que foram modificados.

bin/shadwire diff
bin/shadwire diff --json
bin/shadwire diff --exit-code    # non-zero when there is drift (fails CI)

update

bin/shadwire diff button          # look first
bin/shadwire update button --yes  # then overwrite

update sobrescreve edições locais

Rode diff antes. O update até lista o que substituiu (overwritten e diffs na saída JSON), mas só depois que já substituiu. Veja como manter suas edições.

remove

bin/shadwire remove chart --yes

Apaga só os arquivos que pertencem aos componentes removidos. Os arquivos base compartilhados e os que outro componente instalado ainda usa continuam no lugar. Pins de importmap que ninguém mais usa aparecem na saída, mas não são removidos.

Flags

Flag	Comandos	Efeito
`--cwd DIR`	todos	Roda em outro diretório de aplicação, em vez do atual.
`--registry URL`	todos	Lê de outro registry. Aceita URLs https:// e file://; use file:// para testar um registry gerado localmente.
`--json`	todos, menos version	Mostra a saída em JSON em vez de texto para humanos, para agentes e CI.
`--yes, -y`	init, add, update, remove	Aplica mudanças de arquivo e de dependência sem perguntar.
`--overwrite`	add, update	Sobrescreve arquivos modificados localmente sem perguntar.
`--no-deps`	add, update	Não instala os itens do registry de que o componente depende (por padrão, eles são instalados).
`--force`	init	Reescreve um shadwire.json existente e recria o binstub.
`--exit-code`	diff	Sai com código diferente de zero quando algum arquivo mudou, para o CI poder falhar.

Erros e código de saída

Código de saída 0 significa que o comando funcionou. Se um comando não conseguir instalar uma dependência, ele avisa e sai com código diferente de zero, então dá para confiar no código de saída sem precisar conferir o Gemfile.

$ shadwire init --yes
Initialized shadwire (2 base files).
  create  app/components/ui_component.rb
  FAILED  view_component (bundle add failed)
Failed to install: view_component. Run `bundle add view_component` in the app
and re-run this command.
$ echo $?
1

Cada erro é uma única linha no stderr dizendo o que fazer. Estas são as mensagens para um shadwire.json malformado, um registry fora do ar, um registry que devolve HTML e um argumento faltando:

shadwire.json is not valid JSON: expected object key, got 'not' at line 1 column 3
Could not reach the registry at https://…/index.json: getaddrinfo(3): Name or service not known
add requires at least one component name

A exceção é o status, que nunca falha: devolve "rails": false, registryError ou configError como campos e sai com 0. Por isso dá para rodá-lo em qualquer lugar, inclusive no contexto de um agente.

No CI

Todo comando aceita --yes (sem perguntas), --json (saída em JSON) e --cwd (rodar em outro diretório). Este job faz o build falhar quando um componente instalado não bate mais com o registry:

- name: Install dependencies (with the development group)
  run: bundle install

# Fails when an installed file has diverged from the registry.
- name: Check for Shadwire drift
  run: bin/shadwire diff --exit-code

O job precisa do grupo development instalado; sem ele, bin/shadwire não roda.