@noclaf/cli-docs

Visual de documentação do @noclaf/cli-core. Recebe o modelo de docs (JSON) e devolve um HTML único e autocontido: sem servidor, sem porta, sem asset externo. Dá pra abrir local ou mandar o arquivo pra quem vai consumir o CLI.

Cada guia, os comandos gerais e cada módulo viram uma página, com os comandos de CLI, as tools MCP e o contrato de backend (tabelas e funções) do módulo. O que tem na página:

• logo e nome da marca, seletor de versão (product.versions);
• busca (/ ou ⌘K) e tema claro/escuro;
• "Nesta página" com a seção atual destacada;
• blocos de código coloridos (bash, JSON, tabelas) com botão de copiar;
• "Copiar documentação" no topo (todas as páginas em Markdown, para uma IA);
• "Copiar página" (Markdown) e o menu com: ver como Markdown, copiar prompt de implementação (instruções + contrato, para uma IA) e baixar PDF (impressão).

Histórico de versões

O modelo pode carregar um history (opcional, aditivo: DOCS_MODEL_VERSION continua 1). Com ele, o visual ganha:

• seletor de versão que troca de verdade (#@0.11.0/<id>): as páginas de uma versão antiga são remontadas a partir de um resumo estrutural (sem descrições) e trazem um aviso com atalhos para a versão atual e para a comparação;
• "Comparar versões" (#compare/<de>..<para>, /text inclui mudanças de texto): por módulo, o que foi adicionado (+), alterado (~) e removido (−), com parâmetros, enums, colunas e comandos que mudaram de módulo; "Copiar página" exporta em Markdown;
• "Changelog" (#changelog[/<versão>]): uma seção por versão, com resumo calculado da comparação, novidades, correções e as mudanças do core.

Sem history, ou com um format desconhecido, o histórico é ignorado e a documentação aparece como antes.

O formato fica em src/history/types.ts (DOCS_HISTORY_FORMAT): a versão mais nova guarda um resumo completo (head) e cada versão anterior, só o delta em relação à seguinte. Quem publica monta o histórico com a API pura exportada pelo pacote:

import { appendRelease, historyBudget, snapshot } from '@noclaf/cli-docs';

const next = appendRelease(previousHistory, { version, date, core, notes }, snapshot(model), packageName);
historyBudget(next); // { head, deltas, total, status: 'ok' | 'warn' | 'fail', problems }

Orçamento: head até 16 KB, cada delta até 4 KB, arquivo todo até 64 KB (aviso) e 128 KB (falha). Textos das notas passam sempre pelo escape/Markdown do visual.

Uso

Quem chama é o core (<cli> docs). Direto:

import { renderDocs, type DocsModel } from '@noclaf/cli-docs';

const html = renderDocs(model); // string com o HTML pronto

O formato do modelo está em src/model.ts e é versionado por DOCS_MODEL_VERSION. Modelo de outra versão é recusado.

Desenvolvimento

bun install
bun run dev                 # preview em http://localhost:4173 com fixtures/sample.json
bun run dev outro.json      # preview com outro modelo
bun test
bun run lint
bun run build               # dist/index.js + dist/template.html

O visual é TypeScript puro com CSS: nada de framework. O build empacota src/app/ num template.html só, com o JS e o CSS embutidos e um slot onde o modelo é injetado.

fixtures/sample.json é um modelo real gerado a partir do core com todos os módulos. fixtures/history.json é uma cadeia sintética de 3 versões (bun scripts/history-fixture.ts a regenera) que o bun run dev junta ao sample.

Publicação

Tag v* dispara .github/workflows/publish.yml (npm via trusted publisher).