abworks-dev/readme-banner

O que readme-banner faz?

Gere SVGs com tema claro e escuro usando a CLI local; edite o README apenas quando o usuário solicitar explicitamente inserir/atualizar o banner. Consulte a referência de configuração para configuração e restrições específicas. Não invente flags da CLI ou campos de configuração sem consultar a documentação.

Primeiro, confirme o escopo da operação

1. Determine o caminho absoluto do repositório alvo. O repositório do projeto do usuário pode ser diferente do diretório do código-fonte da ferramenta readme-banner. Leia o diretório de trabalho atual e verifique o README / metadados do projeto alvo; o diretório da skill, o checkout da ferramenta e o diretório padrão do terminal não equivalem automaticamente ao alvo.
2. Se houver ambiguidade sobre o alvo, pergunte ao usuário primeiro; não adicione um banner à própria ferramenta só porque o diretório atual é readme-banner. Gere configuração e imagens dentro da ferramenta apenas quando o usuário escolher explicitamente o repositório da ferramenta como alvo.
3. Esclareça se a solicitação é "apenas gerar recursos / trecho de pré-visualização" ou "inserir / atualizar o README especificado". Sem uma solicitação explícita de edição do README, nunca passe a flag --readme nem edite o README por meio de outra ferramenta de edição de arquivos. Confirme o nome do arquivo; não altere automaticamente todas as versões de idioma ou todos os diretórios de README.
4. Verifique configurações, imagens, blocos gerenciados e alterações não commitadas existentes. Preserve modificações não relacionadas; não faça reset, clean, delete recursos antigos ou substitua outros documentos do usuário. Se uma configuração já existir, leia-a e reutilize-a; substituições exigem confirmação adicional, não use --force por hábito.

Escolha a aparência

• preset use primeiro ascii; ele é o primeiro renderizador, não o nome de "todos os temas".
• theme selecione independentemente: terminal verde terminal, ocean azul-ciano, neon roxo-rosa, minimal monocromático. Siga a preferência do usuário; quando não especificado, sugira brevemente com base no espírito do projeto, não invente um id de tema personalizado.
• Obtenha título, subtítulo e arte opcional embutida. Evite usar logotipos de marca sem solicitação; donut é um exemplo sem marca. Peças embutidas que dependem do relógio em tempo real serão rejeitadas para que o artefato possa ser reproduzido; não contorne essa validação.
• O título ASCII tem no máximo 120 caracteres e deve ser suportado por todas as fontes embutidas selecionadas; caracteres chineses, emoji e pontuação não suportada não podem ser excluídos silenciosamente. Quando for necessário um título curto alternativo em inglês, peça confirmação ao usuário; o texto original pode ser colocado em uma tagline de texto simples de no máximo 240 caracteres.
• mixed preserva maiúsculas/minúsculas do inglês; outras fontes são convertidas para maiúsculas. O limite de 20/60 caracteres para URLs upstream não se aplica à CLI local, mas 120 caracteres não é uma garantia estética. Títulos longos devem ser encurtados, ou considere slim ou redução da arte.
• Títulos animados use glint ou type; quando o usuário solicitar banner estático, use still. still também congela a arte embutida; o SVG ainda retém os dados do quadro de animação da arte, portanto não garante redução significativa no tamanho do arquivo.

Use uma entrada CLI confiável

Requer Node.js >=22, verifique a versão disponível primeiro.

Já dentro do checkout do código-fonte da ferramenta

Se o ambiente de tarefa já possui o código-fonte desta ferramenta, use-o diretamente, não baixe o mesmo tool da rede:

1. Execute npm install no diretório do código-fonte da ferramenta; prepare compilará o TypeScript. Não instale dependências dentro do projeto alvo do usuário apenas para construir a ferramenta.
2. Verifique a entrada local:

node "/caminho/absoluto/readme-banner/bin/readme-banner.mjs" --help

3. Daqui em diante, mantenha a entrada local do Node e sempre passe explicitamente o alvo --cwd. Mesmo que o diretório de trabalho do comando seja o checkout da ferramenta, a separação do alvo não pode ser omitida.

Sem checkout local

Use a tag fixa do Git v0.1.0 do repositório público abworks-dev/readme-banner para entrada; isso requer Git, rede e permissão do usuário para instalar/executar código de terceiros confiável:

npx --yes --package github:abworks-dev/readme-banner#v0.1.0 readme-banner --help

@readme-banner/cli é apenas um nome de pacote local que ainda não foi publicado no npm. Não use npx @readme-banner/cli ou invente outros pacotes npm. Se a instalação falhar, reporte o erro real, não recorra a fontes desconhecidas, versões mais recentes não verificadas ou serviços SVG remotos.

Se aparecer EALLOWGIT, não modifique automaticamente as configurações globais do npm. Apenas quando o usuário já autorizou a instalação/execução deste repositório confiável e a política da organização permitir, o npm que suporta essa opção pode usar npx --allow-git=root --yes --package github:abworks-dev/readme-banner#v0.1.0 readme-banner … uma vez. Pergunte quando não autorizado; pare quando a política da organização restringir. Quando o npm antigo não reconhecer a opção, use o comando normal ou instalação a partir do código-fonte autorizado.

Os exemplos abaixo usam a entrada local; para entrada remota, substitua todo o prefixo node … pelo npx --yes --package … readme-banner completo acima, sem alterar a semântica dos parâmetros subsequentes.

Fluxo de execução: init → generate → check

1. Criar ou reutilizar configuração

node "/caminho/absoluto/readme-banner/bin/readme-banner.mjs" init --cwd "/caminho/absoluto/projeto-alvo" --config "banner.config.json" --preset ascii --theme ocean --title "MEU PROJETO" --tagline "Construa algo útil" --art donut --effect glint

• init apenas cria configuração, não gera imagens, não modifica o README; em seguida, deve executar generate.
• Se a configuração já existir, leia-a primeiro e faça modificações mínimas de acordo com a intenção do usuário, ou reutilize diretamente; não use --force automaticamente para recriar. Omita os parâmetros correspondentes quando subtítulo ou arte não forem necessários.
• Fonte, cor, sombra, posição, velocidade, fundo etc. são definidos por meio dos campos suportados no JSON. Leia primeiro a referência de configuração, não invente opções como init --font.
• A configuração só pode ser JSON; não crie configurações que executem código, não instale plugins de configuração arbitrários, não puxe ou injete SVGs remotos fornecidos pelo usuário.

2. Gerar recursos (modo padrão)

node "/caminho/absoluto/readme-banner/bin/readme-banner.mjs" generate --cwd "/caminho/absoluto/projeto-alvo" --config "banner.config.json"

Por padrão, escreve banner.light.svg e banner.dark.svg no outputDir da configuração e gera um trecho <picture>. Este comando não deve modificar o README. Se o usuário solicitar apenas recursos, pare por aqui, não insira o trecho furtivamente no README.

3. Inserir apenas com autorização de edição do README

node "/caminho/absoluto/readme-banner/bin/readme-banner.mjs" generate --cwd "/caminho/absoluto/projeto-alvo" --config "banner.config.json" --readme "README.md"

--readme só pode especificar um arquivo .md existente. A CLI mantém o bloco entre <!-- readme-banner:start --> e <!-- readme-banner:end -->. Verifique se o conteúdo fora do bloco permanece inalterado; no mesmo README, mesmo que a marcação completa apareça em exemplos de código, ela será tratada conservadoramente como marcação duplicada, portanto não insira pares de marcação extras para demonstração. Quando houver anomalias na marcação, investigue o erro, não exclua texto não relacionado nem expanda o escopo de substituição. Use o trecho gerado real: URLs devem ser relativas ao README alvo, codificadas por URI segmento por segmento, texto alternativo deve ser escapado em HTML, não monte HTML não escapado manualmente.

4. Verificar resultados

# Tarefa sem autorização de edição do README verifica apenas as imagens
node "/caminho/absoluto/readme-banner/bin/readme-banner.mjs" generate --cwd "/caminho/absoluto/projeto-alvo" --config "banner.config.json" --check

# Apenas quando a tarefa envolve explicitamente o README especificado, verifique também o bloco gerenciado
node "/caminho/absoluto/readme-banner/bin/readme-banner.mjs" generate --cwd "/caminho/absoluto/projeto-alvo" --config "banner.config.json" --readme "README.md" --check

• --check não escreve arquivos; artefatos ausentes ou desatualizados devem falhar. Em caso de falha, relate a causa, não ignore o código de saída nem afirme que uma verificação não executada foi aprovada.
• Verifique se ambos os SVGs existem e os caminhos estão corretos; quando houver ferramenta de visualização, verifique o efeito real do tema claro/escuro, título longo e arte. Não confunda a geração bem-sucedida do SVG com a garantia de que todos os clientes Markdown reproduzirão a animação.
• Use generate --json para resultados legíveis por máquina; metadados podem ser vistos por meio de presets --json e themes --json.
• Quando houver erro de proteção de caminho fora dos limites, link simbólico ou link físico, confirme o alvo do usuário e escolha um arquivo comum seguro dentro do diretório raiz; links físicos com nlink > 1 em arquivos existentes serão rejeitados. Não desative a proteção nem mova o arquivo para fora da raiz para "contornar".

Comandos e segurança de arquivos

• Todas as chamadas de execução definem explicitamente o diretório de trabalho correto e passam o alvo --cwd; não dependa do diretório padrão do ambiente do agente.
• Títulos, caminhos e subtítulos são parâmetros de dados. Priorize o uso de APIs de execução que aceitam arrays de parâmetros; ao usar shell, cite/escape cada parâmetro de acordo com as regras desse shell. As aspas duplas no exemplo são adequadas apenas para valores de espaço reservado simples ali; não podem defender contra todas as interpolações do shell; não concatene entradas não confiáveis em comandos, eval ou scripts sem escape. Caminhos do Windows também devem ser citados individualmente.
• Modifique apenas a configuração autorizada pelo usuário, recursos gerados e blocos gerenciados especificados; não altere código de negócios, documentos não relacionados ou alterações existentes do usuário.
• Não faça commit, push, crie repositório remoto, publique release, faça upload de imagens, publique pacote npm ou dispare qualquer outra publicação remota automaticamente. Isso requer solicitações independentes e explícitas.

Relatório de entrega

Relatório breve: repositório alvo, preset/tema/título adotados, duas imagens geradas, se o README foi modificado e sua localização, e o resultado real da verificação executada. Quando não houver autorização para o README, declare claramente "README não modificado" e retorne o trecho gerado para o usuário escolher. Liste substituições de glifo que ainda precisam de confirmação do usuário, títulos muito longos ou problemas de compatibilidade do visualizador; não afirme que testes não executados foram aprovados.