Mirofy

O que Mirofy faz?

Crie um diagrama HTML interativo e autocontido a partir de uma pequena especificação JSON tipada. A saída estática é o padrão; habilite a animação somente quando o usuário solicitar uma demonstração ou apresentação.

Varredura primeiro: derive o diagrama de um repositório real

Quando o diagrama deve descrever código que existe, não o crie de memória. Derive-o:

npm run scan      # repositório -> grafo de evidências (fatos e lacunas)
npm run model     # evidências + documentos -> um modelo de sistema
npm run compile   # modelo -> uma visão limitada com intenção

Cada etapa relata o que NÃO pôde determinar. scan registra uma lacuna para cada arquivo que não pôde analisar, compile registra cada objeto que omitiu e por quê. Leve essas informações adiante para o usuário; um diagrama que omite silenciosamente metade de um sistema é pior do que um que informa o que deixou de fora.

Use o caminho rápido abaixo quando o usuário estiver descrevendo algo que ainda não existe, ou quando nenhum repositório estiver disponível.

Caminho rápido de criação

Use este caminho limitado para geração comum. Não leia a Referência Opcional do Runtime do Visualizador, a menos que o usuário pergunte sobre esses recursos.

1. Escolha architecture, workflow, sequence, dataflow ou lifecycle a partir da pergunta.

2. Leia um esquema correspondente em schemas/, schemas/common.schema.json e um exemplo JSON correspondente em examples/. Leia apenas esses arquivos. Criação original significa novos IDs estáveis, terminologia de domínio e layout; use o exemplo para a forma dos campos, não para fatos. Quando a identidade real do produto for importante, consulte node bin/mirofy.mjs brands "<nome>" --json; leia references/brand-marks.md apenas para uma marca desconhecida com uma URL fornecida pelo usuário.

3. Artefato primeiro: a próxima ação da ferramenta deve escrever o candidato. Escreva o candidato antes de inspecionar os detalhes 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 standard denso. Comece com rotas e rótulos automáticos. Não adicione via, channelX, channelY ou labelAt antes que um diagnóstico solicite um; 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/mirofy.mjs validate <tipo> <candidato.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 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 exato meta.quality_profile, 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/mirofy.mjs deliver <tipo> <candidato.json> <saida.html> --quality showcase --json
   

   Uma saída não 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 objetiva 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 honestidade.

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 dois reparos focados falharem.

Roteador de tipos

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

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

Entrada Mermaid

node bin/mirofy.mjs import mermaid <entrada.mmd> [saida.json] [--json]

flowchart/graph → architecture, sequenceDiagram → sequence, stateDiagram(-v2) → lifecycle.

O importador nunca adivinha: qualquer linha que não puder ler se torna uma lacuna com seu número de linha, então relate o que não foi transportado em vez de considerar o resultado completo. Ele também não atribui posições — uma arquitetura convertida usa layout.mode: "grid", e uma expansão pode colocar uma aresta através de um nó, o que falha no portão clean-flow sempre ativo. Sempre valide após importar. Leia a fonte também para significado: o importador transporta topologia, não julgamento de domínio, então rótulos e tipos geralmente merecem reescrita.

Reparando geometria

Quando a validação relatar componentes sobrepostos, não edite coordenadas manualmente uma a uma:

node bin/mirofy.mjs repair <tipo> <entrada.json> [saida.json] --safe

--safe é obrigatório porque isso reescreve coordenadas criadas. O reparo move apenas componentes envolvidos em uma sobreposição, cada um pela menor correção que limpa a lacuna de 8px do validador, imprime um recibo de cada ajuste e toca apenas na geometria e nada mais — nunca em um rótulo, tipo, conexão ou id. Ele revalida e nomeia o que o deslocamento não pode corrigir (roteamento, posicionamento de rótulo) em vez de deixar para a próxima execução redescobrir.

Invariantes de criação

• Um caminho principal óbvio; ramificações laterais saem do nó mais próximo do caminho principal. Remova arestas de baixo valor antes de adicionar controles de roteamento.
• Omita meta.visual_preset por padrão para que todo diagrama abra em classic, independentemente de seu modo de cor resolvido ser claro ou escuro. Modo de cor e predefinição visual são independentes: alternar Claro / Escuro deve preservar a predefinição atual. Defina signal-flow, blueprint ou editorial somente quando o usuário solicitar explicitamente esse estilo visual.
• Omita meta.subtitle por padrão. Nunca invente um subtítulo que repita o título, nós ou cartões; inclua uma linha curta de suporte apenas quando o usuário solicitar explicitamente.
• Trate o visualizador de desktop independente como um artefato de primeira tela por padrão, não uma faixa rasa. Gere um artefato responsivo para laptops e monitores externos — nunca HTML específico de dispositivo ou topologia alternativa. O visualizador pode adaptar apenas a largura de leitura externa da altura da viewport ativa; ele deve preservar o SVG/viewBox criado, proporções, geometria semântica e fluxo normal do documento. Em um desktop amplo ou alto, use ritmo vertical criado suficiente para que o painel de diagrama e suas cartas de conclusão necessárias ocupem a tela como um todo equilibrado; o redimensionamento em tempo de execução não pode reparar um layout Y muito comprimido ou um meta.viewBox explícito subdimensionado. Antes da entrega, abra o HTML real em 1440×900, 1600×1000 e 1920×1080; adicionalmente, verifique 2048×1320 sempre que a composição for destinada a um monitor grande. Exija document.documentElement.scrollWidth <= window.innerWidth e scrollHeight <= window.innerHeight em todos os tamanhos verificados, verificando visualmente que o diagrama permanece confortavelmente legível e verticalmente equilibrado na maior viewport verificada. Repare o estouro removendo apenas conteúdo genuinamente redundante ou compactando espaçamento antes de reduzir nós, rótulos ou o painel principal. Se a maior viewport ainda tiver uma faixa inferior conspicuamente vazia no limite de largura do visualizador, redistribua as posições Y criadas e aumente a altura da viewBox proporcionalmente; não adicione texto de preenchimento ou cartões decorativos. Nunca falsifique uma aprovação com overflow: hidden, conteúdo cortado, um rolar interno de diagrama, altura SVG esticada ou tipografia menor. Layouts estreitos/móveis podem rolar verticalmente quando a contenção exigir.
• Omita meta.legend para o padrão auto verdadeiro. Quando necessário, use apenas mode: auto|all|hidden e entries.<kind>.label|visible suportados pelo renderizador; os rótulos nunca alteram a semântica.
• Escolha um idioma principal criado a partir de uma escolha explícita do usuário; caso contrário, siga a solicitação ou o idioma dominante da conversa. meta.locale controla apenas a IU do visualizador de propriedade do renderizador: use "en" ou "zh-CN" para o idioma principal suportado correspondente. Para todos os outros idiomas, omita meta.locale e divulgue explicitamente que a IU fixa do visualizador e <html lang> retornam ao inglês. O renderizador nunca traduz o conteúdo criado. Consulte references/authoring-contract.md para obter detalhes.
• Preserve nomes exatos de produtos, identificadores de código, comandos, protocolos, caminhos de API e nomes de ambiente. Eles podem permanecer em inglês dentro de texto localizado, mas nunca justifique deixar a prosa explicativa circundante em outro idioma.
• A identidade da marca é opcional e explícita. Coloque um ID interno canônico em brand quando o nó nomear esse produto real. Se nenhuma predefinição corresponder e o usuário forneceu a URL oficial HTTP(S), primeiro execute node bin/mirofy.mjs brands capture "<url>" --json, então crie o objeto brand com digest fixo retornado. Renderização e validação nunca realizam uma captura sem digest fixo. Caso contrário, omita brand. Nunca infira uma marca a partir de uma função vaga como "banco de dados" e nunca deixe um selo substituir o type, rótulo ou fatos de relacionamento semânticos.
• Para diagramas de sequência, omita meta.column_fit para o layout fixed estável. Defina-o como "spread" quando uma viewBox larga deixaria espaço horizontal não utilizado ou quando rótulos significativos de participantes não couberem nas caixas fixas; não encurte rótulos semânticos antes de tentar spread.
• Os tipos de componente são frontend, backend, database, cloud, security, messagebus e external; as variantes são default, emphasis, security e dashed.
• Os rótulos de relacionamento são dados semânticos. Quando um colidir, mova o rótulo, ajuste a rota ou o espaçamento, então encurte a redação preservando o significado. Exclua um rótulo apenas quando ambos os pontos finais implicarem totalmente o relacionamento e ele não contiver protocolo, ação, direção, comportamento síncrono/assíncrono ou mecanismo entre limites; explique por que o rótulo excluído é redundante. Nunca exclua um rótulo significativo apenas para passar em showcase.
• Omita meta.engineering_profile por padrão. A redação de limites de região, cluster e segurança não o ativa por si só. Ative deployment-ownership apenas quando o usuário solicitar explicitamente uma topologia de implantação de produção, transferência de propriedade ou revisão de implantação com falha fechada e os fatos de origem forem conhecidos. Uma vez ativado, não deve remover o perfil de engenharia apenas para passar na validação; repare os fatos ou relate os diagnósticos com honestidade.
• Espaçamento significa lacuna clara, não distância central. Para um rótulo de relacionamento, a lacuna clara deve exceder sua largura de máscara medida; use a ordem de reparo que preserva o rótulo antes de considerar a exclusão.
• 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 Portas é um comportamento padrão do renderizador para arquitetura, fluxo de trabalho, fluxo de dados e ciclo de vida. Ela ignora relacionamentos únicos e via, channelX, channelY, labelAt ou rotas não auto explícitos. Portas quase paralelas usam uma ponte externa para que o roteamento automático não possa criar um segmento menor que 8px ou uma curva interna menor que 16px. Arquitetura mantém separadamente portas automáticas voltadas desobstruídas (left/right ou top/bottom) em um eixo compartilhado quando seu deslocamento for menor que 16px e ambas as portas mantiverem distância dos cantos. Se exatamente um ponto final foi distribuído, apenas o ponto final não compartilhado pode mover-se para esse eixo; se ambos os pontos finais foram distribuídos, mantenha a ponte externa para que as portas concorrentes permaneçam distintas.
• 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 enums de campo, matemática de espaçamento, posicionamento automático de porta, 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 instantâneo privado no mesmo diretório, renderiza e verifica esse instantâneo, comita atomicamente o HTML e relata SHA-256 mais contagens de bytes para especificação e artefato.

Após a entrega, colete evidências de desktop limitadas sem modificar ou re-renderizar o HTML confiável:

node bin/mirofy.mjs visual-check <saida.html> --json

visual-check mede a contenção em 1440×900, 1600×1000, 1920×1080 e 2048×1320; captura capturas de tela claras/escuras nos tamanhos menor e maior; e escreve uma folha de contato de caminho relativo mais sidecars JSON ao lado do artefato. Seu recibo automatizado sempre relata visualReview: "pending": capturas de tela são evidências para inspeção, nunca uma reivindicação automática de polimento. Saída 0 significa contenção e capturas passaram, 1 significa estouro ou falha de captura, e 2 significa que Chrome/Chromium não estava disponível e o recibo é skipped. O comando nunca altera o HTML entregue. Adicione --open apenas quando o usuário quiser uma prévia local imediata. Para um loop ativo de criação de desktop, o comando opcional é:

node bin/mirofy.mjs preview <tipo> <entrada>.json <saida>.html --quality showcase

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

Capacidades opcionais do visualizador

O HTML gerado já contém alternância de tema, pan/zoom, pesquisa, foco, rastreamento de relacionamento, visualizações semânticas, apresentação e exportações verdadeiras. Estas são capacidades do leitor, não trabalho extra de criação. meta.animation: "trace" é opt-in; meta.views é opcional e deve conter no máximo cinco capítulos selecionados. Leia references/viewer-runtime.md apenas quando o usuário solicitar explicitamente Cartões de Compartilhamento, Cartões de Rota/Alcance, movimento, histórias guiadas, links profundos, apresentação, pesquisa/foco ou outro recurso do Runtime do Visualizador.

Configuração e fallback

Instalar a skill é opcional.

…

[truncado para tradução]