cubxxw/archify

O que archify faz?

Crie um diagrama HTML autônomo e interativo a partir de uma pequena especificação JSON. A saída estática é o padrão; ative o movimento apenas quando o usuário pedir uma demonstração ou apresentação.

Caminho rápido de autoria

Use este caminho delimitado para geração comum. Não leia a referência opcional do Viewer Runtime, a menos que o usuário pergunte sobre esses recursos.

1. Escolha architecture, workflow, sequence, dataflow ou lifecycle na pergunta.

2. Leia um esquema correspondente em schemas/, schemas/common.schema.json e um exemplo JSON correspondente em examples/. Leia apenas esses arquivos. Autoria nova significa novos IDs estáveis, terminologia de domínio e layout; use o exemplo para a forma dos campos, não para os fatos.

3. Artefato primeiro: a próxima ação da ferramenta deve escrever o candidato. Escreva o candidato antes de inspecionar os internos do renderizador. Não planeje coordenadas exatas em prosa. Comece com um caminho principal claro, ramificações laterais curtas, rótulos esparsos e no máximo 12 nós primários. Defina meta.quality_profile como "showcase", a menos que o usuário solicite explicitamente um mapa denso standard. Comece com rotas e rótulos automáticos. Não adicione via, channelX, channelY ou labelAt antes que um diagnóstico os solicite; aplique no máximo um controle de geometria diagnosticado por reparo.

4. Valide após cada edição do candidato e imediatamente antes da entrega:

   node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json
   

   Um recibo com apenas 4 verificações de artefato é validação básica, nunca aceitação de showcase. Uma aprovação de showcase deve relatar todas as 9 verificações de artefato com 0 erros de composição e 0 avisos. Se o candidato omitir ou escrever incorretamente o campo meta.quality_profile exato, corrija-o antes da geometria. Uma validação final aprovada congela o candidato: nunca o edite depois.

5. Para um HTML entregue, deliver é o comando de aceitação final:

   node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
   

   Uma saída diferente de zero nunca pode ser descrita como sucesso. Se a validação falhar, altere apenas o subject diagnosticado, verifique evidence, escolha entre supportedFixes e execute novamente. Continue a correção focada enquanto a contagem de erros objetivo atingir um novo mínimo. Se duas rodadas consecutivas não melhorarem essa melhor contagem, pare e relate os diagnósticos não resolvidos com veracidade.

Não leia renderers/shared/geometry.mjs, código-fonte do renderizador, código-fonte do validador, testes ou benchmarks antes do primeiro candidato. Inspecione a implementação apenas para um diagnóstico interno não suportado ou após duas correções focadas falharem.

Nota sobre ciclo de vida: as colunas de fase 0..4 ocupam o trilho principal; as colunas de evento/resultado 0..2 alinham-se abaixo das fases posteriores. Um estado recuperável usa type: "failure" mais uma transição real de volta ao estado ativo.

Roteador de tipos

Tipo	Uso para
architecture	Componentes, serviços, limites de nuvem/segurança, infraestrutura
workflow	Processos, portões de aprovação, chamadas de ferramentas, runbooks, CI/CD
sequence	Cadeias de chamadas de API, ciclos de vida de requisição, rastros assíncronos, retornos
dataflow	Pipelines, ETL/ELT, linhagem, governança, consumidores
lifecycle	Transições de estado/status, repetições, estados de espera e terminais

Quando ambíguo, execute node bin/archify.mjs guide "<scenario>" --json. Exemplos de prova de cenário são referências estruturais, não fatos a copiar.

Entrada Mermaid

Leia Mermaid para topologia e significado, então crie um novo JSON Archify; não renderize mecanicamente o estilo Mermaid.

• flowchart / graph → workflow, ou architecture para um mapa de componentes.
• sequenceDiagram → sequence; participantes tornam-se participantes semânticos e setas tornam-se mensagens.
• stateDiagram → lifecycle; estados e transições mantêm o significado, não o estilo Mermaid.

Invariantes de autoria

• Um caminho principal óbvio; ramificações laterais saem do nó do caminho principal mais próximo. Remova arestas de baixo valor antes de adicionar controles de roteamento.
• Omita meta.legend para o padrão verdadeiro auto. Quando necessário, use apenas mode: auto|all|hidden e entries.<kind>.label|visible suportados pelo renderizador; rótulos nunca mudam a semântica.
• Os tipos de componente são frontend, backend, database, cloud, security, messagebus e external; as variantes são default, emphasis, security e dashed.
• Espaçamento significa intervalo claro, não distância central. Para um rótulo de relacionamento, o intervalo claro deve exceder sua largura de máscara medida; caso contrário, omita o rótulo ou mova-o deliberadamente.
• Rotas automáticas possuem seus próprios lados de ponto final. Um lado é um contrato de direção: o primeiro e o último segmento devem sair/entrar perpendicularmente a esse lado.
• A Distribuição Automática de Portos é um comportamento padrão do renderizador para architecture, workflow, data-flow e lifecycle. Ela ignora relacionamentos únicos e via, channelX, channelY, labelAt ou rotas não auto explícitas. Portos quase paralelos usam uma ponte externa para que o roteamento automático não crie um segmento sub-8px ou uma curva interna sub-16px.
• Nunca aceite uma aresta cruzando um nó opaco não relacionado, um corredor compartilhado ambíguo ou um rótulo de relacionamento mascarando outra rota.

Leia references/authoring-contract.md apenas quando precisar de enumerações de campo, matemática de espaçamento, regras de reparo de geometria, evidências de repositório ou posicionamento específico de modo.

Entrega

Use validate durante o reparo e deliver uma vez para aceitação final. A entrega congela os bytes exatos da especificação em um snapshot privado no mesmo diretório, renderiza e verifica esse snapshot, confirma atomicamente o HTML e relata SHA-256 mais contagens de bytes para a especificação e o artefato.

Adicione --open apenas quando o usuário quiser uma pré-visualização local imediata. Para um ciclo de autoria ativo em desktop, o comando opcional é:

node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase

Nunca inicie a pré-visualização por padrão. Leia references/delivery-contract.md ao usar pré-visualização, evidências de repositório, recibos de exportação, revisão visual ou abertura pós-confirmação.

Capacidades opcionais do visualizador

O HTML gerado já contém troca de tema, pan/zoom, busca, foco, rastreamento de relacionamentos, visualizações semânticas, apresentação e exportações verdadeiras. Estas são capacidades do leitor, não trabalho extra de autoria. meta.animation: "trace" é opcional; meta.views é opcional e deve conter no máximo cinco capítulos selecionados.

Leia references/viewer-runtime.md apenas quando o usuário perguntar explicitamente sobre Cartões de Compartilhamento, Cartões de Rota/Alcance, movimento, histórias guiadas, links profundos, apresentação, busca/foco ou outro recurso do Viewer Runtime.

Configuração e fallback

Nenhuma instalação é necessária dentro do pacote da skill. Verifique com:

node bin/archify.mjs doctor
node bin/archify.mjs demo <output-directory>

Quando o acesso ao shell não estiver disponível, coloque manualmente o SVG da arquitetura em assets/template.html, use classes CSS semânticas em vez de cores inline e siga o contrato de revisão visual em references/delivery-contract.md.

Saída

Retorne o caminho HTML verificado, o tipo de diagrama, o resumo da validação, o recibo da especificação/artefato e o status da revisão visual verdadeira. Não reivindique sucesso para um comando com código de saída diferente de zero ou reivindique inspeção visual que você não realizou.