Tailr — o ciclo de revisão

O que Tailr — o ciclo de revisão faz?

Tailr permite que a pessoa com quem você está trabalhando marque seu servidor de desenvolvimento em execução no navegador — clique em um elemento, diga o que está errado — e entregue todas as marcações de uma só vez como um lote. Você aplica o lote e reporta cada marcação conforme ela é aplicada.

As regras abaixo são o protocolo completo. São as mesmas regras que tailr init escreve no AGENTS.md / CLAUDE.md do projeto; este plugin as carrega em seu lugar, para que nada no repositório do usuário precise ser editado.

Tailr — marcação visual do revisor

O revisor marca o aplicativo em execução no navegador e entrega as alterações como um único lote. Uma sessão está ativa quando .tailr/session.json existe; se não existir, inicie uma como um processo de fundo de longa duração — ele deve permanecer ativo, então não bloqueie sua vez esperando por ele:

npx tailr --target http://localhost:<porta do servidor dev>

Ele imprime uma URL de revisão (geralmente http://localhost:4100). Diga ao revisor para usar essa URL, não a porta original. O Tailr faz proxy do aplicativo e injeta sua sobreposição; a fonte não é modificada.

O ciclo é wait → pull → progress por marcação → done ou fail.

Comando	Ferramenta MCP
npx tailr status	tailr_status	há um lote esperando? saída 0 sim · 3 sessão ativa, nada esperando · 2 sem sessão
npx tailr wait	tailr_wait	bloqueia até que Enviar seja pressionado; saída 0 um lote está esperando · 3 tempo esgotado, inicie novamente · 2 sessão encerrada
npx tailr pull	tailr_pull	obtém o lote, impresso como JSON
npx tailr progress <ref>	tailr_progress	reporta uma marcação como aplicada
npx tailr done	tailr_done	a execução foi concluída
npx tailr fail "motivo"	tailr_fail	a execução retornou incompleta

Cada marcação carrega um ref ("01"), um type, a route em que foi feita, um endereço de origem address de melhor esforço, um selector CSS, o texto do elemento e o comment do revisor.

• comment — altere esse elemento conforme descrito
• remove — exclua esse elemento
• text — carrega before/after; altere o texto para after
• point — carrega página x/y em vez de um elemento. O revisor marcou um lugar, não uma coisa: pode querer algo novo ali, ou apenas estar anotando o ponto. O comentário diz qual.

Regras importantes

• Execute wait como um processo de fundo de longa duração e trate sua saída como a notificação. Nunca peça ao revisor para informar que um lote chegou, e nunca faça polling. Inicie-o novamente após cada execução que você encerrar.
• Reporte cada marcação com progress conforme você a aplica, não todas de uma vez no final. O revisor as vê sendo limpas na tela; agrupar faz parecer que nada está acontecendo.
• Sempre feche a execução com done ou fail. Até que você o faça, o revisor não pode enviar outro lote. Se encontrar algo que não pode fazer, use fail com o que realmente deu errado — o Tailr não inventa uma explicação, ele direciona de volta para você.
• Quando o endereço de origem e o seletor discordarem, confie no endereço de origem.
• Uma marcação com "orphaned": true perdeu seu elemento antes de ser enviada. Não adivinhe o que foi pretendido — levante a questão com o revisor.
• Se uma marcação for ambígua, pergunte em vez de escolher uma interpretação.
• Execute estes comandos a partir do diretório do projeto; é assim que o Tailr encontra a sessão.

Executando os comandos a partir deste plugin

Este plugin registra o servidor MCP do Tailr, então tailr_status, tailr_wait, tailr_pull, tailr_progress, tailr_done e tailr_fail estão disponíveis diretamente para você. Prefira-os à CLI: eles estão sempre presentes, enquanto a forma abreviada npx tailr só resolve em um projeto que tenha o Tailr instalado.

Quando você usar a CLI, use o nome completo do pacote para que funcione em um projeto que não tenha instalado nada:

npx -y @gcrft123/tailr <comando>

Iniciar uma sessão é a única etapa sem uma ferramenta MCP, porque a sessão é o servidor com o qual essas ferramentas se comunicam. Inicie-a como um processo de fundo de longa duração — ele deve permanecer ativo, então não bloqueie sua vez esperando por ele:

npx -y @gcrft123/tailr --target http://localhost:<porta do servidor dev>

Se o projeto tiver o Tailr como dependência, o simples npx tailr é equivalente e mais curto.