@neetru/cli 2.28.10 → 2.31.0

package/dist/lib/product-docs/sync.js

@@ -0,0 +1,313 @@
+/**
+ * `neetru docs sync` — publica o `docs/` do produto no registro de docs por
+ * produto do Core (PROTOCOLO_DOCS_PRODUTOS_SAAS §8.1 + PROJ_PRODUCT_DOCS §4.2).
+ *
+ * CONTRATO (lado servidor no Core: PR #571, `src/app/api/cli/v1/products/[slug]/docs/route.ts`):
+ *
+ *   GET  /api/cli/v1/products/{productId}/docs
+ *        → 200 { ok, count, docs: [{ slug, title?, status?, visibility?, sha256?, version?, … }] }
+ *        → 404 { error: { code: 'product_not_found' } }  produto não existe no Core
+ *        → 404 (outro código / sem corpo)                o Core ainda não tem a rota
+ *   POST /api/cli/v1/products/{productId}/docs
+ *        body { slug, content, frontmatter, visibility }
+ *        → 200/201 { ok, slug, docId, gcsPath, sha256, version, bytes, created }
+ *
+ *   - `productId` = slug do produto (o mesmo do `neetru.config.json`).
+ *   - `slug` do doc = caminho relativo a `docs/`, sem `.md` (ex.: `produto/VISAO_DO_PRODUTO`).
+ *   - `content` = corpo SEM o bloco de frontmatter; `frontmatter` vai como objeto
+ *     (mesmo formato do `neetru docs publish` do Core).
+ *   - `visibility` = `public` só quando `audience: publico` E `status: active`;
+ *     todo o resto é `internal`.
+ *
+ * Regras do lado da CLI:
+ *   - Só sobem docs SEM erro no `docs check`; `_archive/` e `_audit/` não sobem.
+ *   - Doc igual ao do Core (mesmo sha256 do conteúdo, título, status e
+ *     visibilidade) não é reenviado.
+ *   - Nada é apagado no Core: doc que só existe lá aparece como "órfão" (a
+ *     remoção de docs de produto ainda não existe no Core).
+ *   - Limites operacionais (D-05): 200 docs / 10 MB por produto e 2 MB por doc
+ *     (413 `doc_too_large` no Core) — conferidos ANTES de enviar.
+ *   - Slug: o Core aceita só `[A-Za-z0-9._-]` por segmento e recusa `__`; arquivo
+ *     com acento/espaço no caminho não sobe (explicado, sem gastar um 400).
+ *   - Rate limit do Core (`cliWrite`, 30 POST/min por IP): no máximo
+ *     `POSTS_PER_MINUTE` envios por janela de 60 s, um por vez; 429/503 esperam o
+ *     `Retry-After` e tentam de novo (até 3 vezes).
+ *   - "Igual ao Core" compara o sha256 do conteúdo E os metadados que o GET
+ *     devolve (title, description, category, subcategory, type, status,
+ *     audience, order, updated…): mudança só de metadado também sobe.
+ *   - Rota ausente (404 sem `product_not_found`) = "o Core ainda não aceita docs
+ *     de produto" — NÃO é erro fatal.
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { apiRequest, CliApiError } from '../api-client.js';
+import { resolveToken } from '../cli-read.js';
+import { parseDoc } from './frontmatter.js';
+import { checkProductDocs, listDocFiles } from './check.js';
+import { topFolder } from './structure.js';
+export const MAX_PRODUCT_DOCS = 200;
+export const MAX_PRODUCT_DOCS_BYTES = 10 * 1024 * 1024;
+/** Teto por doc no Core (`MAX_PRODUCT_DOC_BYTES`, 413 `doc_too_large`). */
+export const MAX_PRODUCT_DOC_BYTES = 2 * 1024 * 1024;
+/** Abaixo do `cliWrite` do Core (30/min por IP), com folga para outro comando na mesma rede. */
+export const POSTS_PER_MINUTE = 25;
+/** Tentativas extras quando o Core responde 429/503. */
+export const MAX_RETRIES = 3;
+/** Espera quando o 429 vem sem `Retry-After` (s) e teto da espera pedida (s). */
+const DEFAULT_RETRY_AFTER_S = 20;
+const MAX_RETRY_AFTER_S = 120;
+/** Metadados que o GET do Core devolve e que a CLI compara (o que vier). */
+export const COMPARED_METADATA = ['title', 'description', 'category', 'subcategory', 'type', 'status', 'audience', 'order', 'updated', 'date'];
+export function visibilityFor(fm) {
+    return fm.audience === 'publico' && fm.status === 'active' ? 'public' : 'internal';
+}
+export function docSlugFor(relInDocs) {
+    return relInDocs.replace(/\\/g, '/').replace(/\.md$/i, '');
+}
+/**
+ * Motivo pelo qual o Core recusaria o slug (mesmas regras de
+ * `productDocSlugSchema`), ou null se ele passa.
+ */
+export function slugProblem(slug) {
+    if (slug.length > 200)
+        return `o caminho tem ${slug.length} caracteres (máximo 200)`;
+    if (slug.includes('__'))
+        return 'o caminho tem "__" (reservado pelo Core)';
+    for (const seg of slug.split('/')) {
+        if (!seg)
+            return 'o caminho tem barra dupla';
+        if (/^\.+$/.test(seg))
+            return 'o caminho tem segmento "." ou ".."';
+        const bad = [...new Set(seg.replace(/[A-Za-z0-9._-]/g, ''))];
+        if (bad.length) {
+            const shown = bad.map((c) => (c === ' ' ? 'espaço' : `"${c}"`)).join(', ');
+            return `"${seg}" tem ${shown} — o Core só aceita letras sem acento, números, ".", "_" e "-"; renomeie (a regra de nome do protocolo já pede MAIÚSCULAS sem acento)`;
+        }
+    }
+    return null;
+}
+function sha256(s) {
+    return createHash('sha256').update(s, 'utf8').digest('hex');
+}
+function isRouteMissing(err) {
+    if (!(err instanceof CliApiError))
+        return false;
+    if (err.status === 404)
+        return err.code !== 'product_not_found';
+    return err.status === 405 || err.status === 501;
+}
+/** Monta o lote local (sem I/O de rede). */
+export async function collectLocalDocs(repo, taxonomy) {
+    const check = await checkProductDocs(repo, { taxonomy });
+    const errorsByFile = new Map();
+    for (const f of check.findings) {
+        if (f.level !== 'erro')
+            continue;
+        const list = errorsByFile.get(f.file) ?? [];
+        if (!list.includes(f.code))
+            list.push(f.code);
+        errorsByFile.set(f.file, list);
+    }
+    const docs = [];
+    const bloqueados = [];
+    const recusados = [];
+    for (const rel of await listDocFiles(repo)) {
+        const top = topFolder(rel);
+        if (top === '_archive' || top === '_audit')
+            continue;
+        const file = `${repo.docs.root}/${rel}`;
+        // Caminho que o Core recusaria vem ANTES dos erros do check: um nome com
+        // acento/espaço também reprova a regra de nome (NM001), e "renomeie: o Core
+        // só aceita…" é mais útil que só o código da regra.
+        const slug = docSlugFor(rel);
+        const problem = slugProblem(slug);
+        if (problem) {
+            recusados.push({ file, motivo: problem });
+            continue;
+        }
+        const errs = errorsByFile.get(file);
+        if (errs) {
+            bloqueados.push({ file, codes: errs });
+            continue;
+        }
+        const raw = await fs.readFile(path.join(repo.cwd, repo.docs.root, rel), 'utf8');
+        const parsed = parseDoc(raw);
+        const content = parsed.body.replace(/^(\r?\n)+/, '');
+        const bytes = Buffer.byteLength(content, 'utf8');
+        if (bytes > MAX_PRODUCT_DOC_BYTES) {
+            recusados.push({
+                file,
+                motivo: `tem ${(bytes / 1024 / 1024).toFixed(2)} MB; o Core aceita até 2 MB por doc — divida em docs menores`,
+            });
+            continue;
+        }
+        docs.push({
+            file,
+            slug,
+            content,
+            frontmatter: parsed.data,
+            visibility: visibilityFor(parsed.data),
+            sha256: sha256(content),
+            bytes,
+        });
+    }
+    return { docs, bloqueados, recusados };
+}
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Normaliza para comparar: null/undefined/'' iguais; números e strings como estão. */
+function normMeta(v) {
+    if (v === null || v === undefined || v === '')
+        return '';
+    return typeof v === 'string' ? v.trim() : JSON.stringify(v);
+}
+/** O doc local é igual ao do Core (conteúdo + metadados que o GET devolve)? */
+export function sameAsRemote(d, r) {
+    if (!r || r.sha256 !== d.sha256)
+        return false;
+    if ((r.visibility ?? d.visibility) !== d.visibility)
+        return false;
+    for (const k of COMPARED_METADATA) {
+        if (!(k in r))
+            continue; // o Core não devolveu esse campo: não dá para comparar
+        if (normMeta(r[k]) !== normMeta(d.frontmatter[k]))
+            return false;
+    }
+    return true;
+}
+/** Janela deslizante: no máximo `limit` envios em 60 s. */
+export function createPacer(limit, now, sleep, onWait) {
+    const sent = [];
+    return async () => {
+        const t = now();
+        while (sent.length && t - sent[0] >= 60_000)
+            sent.shift();
+        if (sent.length >= limit) {
+            const wait = 60_000 - (t - sent[0]) + 50;
+            onWait?.(wait, 'ritmo');
+            await sleep(wait);
+            sent.shift();
+        }
+        sent.push(now());
+    };
+}
+export async function syncProductDocs(repo, opts) {
+    const product = repo.slug;
+    const dryRun = !!opts.dryRun;
+    const base = {
+        status: 'ok', message: '', product, dryRun,
+        enviados: [], inalterados: [], bloqueados: [], falhas: [], recusados: [], orfaos: [], planejados: [],
+    };
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? realSleep;
+    const pace = createPacer(POSTS_PER_MINUTE, now, sleep, opts.onWait);
+    if (!repo.docs.publish) {
+        return { ...base, status: 'desligado', message: '`docs.publish` está false no neetru.config.json: os docs ficam só no repositório.' };
+    }
+    const { docs, bloqueados, recusados } = await collectLocalDocs(repo, opts.taxonomy);
+    base.bloqueados = bloqueados;
+    base.recusados = recusados;
+    base.planejados = docs.map((d) => ({ slug: d.slug, visibility: d.visibility, bytes: d.bytes }));
+    const totalBytes = docs.reduce((n, d) => n + d.bytes, 0);
+    if (docs.length > MAX_PRODUCT_DOCS || totalBytes > MAX_PRODUCT_DOCS_BYTES) {
+        return {
+            ...base,
+            status: 'limite-excedido',
+            message: `O Core aceita até ${MAX_PRODUCT_DOCS} docs e 10 MB por produto; aqui são ${docs.length} docs e ${(totalBytes / 1024 / 1024).toFixed(1)} MB. Arquive o que não é mais usado.`,
+        };
+    }
+    if (docs.length === 0) {
+        return {
+            ...base,
+            status: 'nada-a-enviar',
+            message: bloqueados.length || recusados.length
+                ? 'Nenhum doc que o Core aceite para enviar — rode `neetru docs check` e veja os recusados.'
+                : 'Nenhum doc encontrado em ' + repo.docs.root + '/.',
+        };
+    }
+    const token = opts.token !== undefined ? opts.token : await resolveToken().catch(() => null);
+    if (!token) {
+        return {
+            ...base,
+            status: dryRun ? 'ok' : 'sem-login',
+            message: dryRun ? `Simulação sem login: ${docs.length} doc(s) seriam enviados.` : 'Nenhuma sessão ativa. Rode `neetru login` e tente de novo.',
+        };
+    }
+    const basePath = `/api/cli/v1/products/${encodeURIComponent(product)}/docs`;
+    let remote;
+    try {
+        const res = await apiRequest(basePath, { token, timeoutMs: 15_000 });
+        remote = Array.isArray(res?.docs) ? res.docs : [];
+    }
+    catch (err) {
+        if (isRouteMissing(err)) {
+            return { ...base, status: 'core-sem-suporte', message: 'O Core ainda não aceita docs de produto. Os docs continuam no repositório; rode `neetru docs sync` de novo quando o Core tiver a rota.' };
+        }
+        if (err instanceof CliApiError && err.status === 404) {
+            return { ...base, status: 'produto-nao-encontrado', message: `O produto "${product}" não existe no Core (ou está arquivado).` };
+        }
+        return { ...base, status: 'falha', message: `Falha ao consultar os docs no Core: ${err.message}` };
+    }
+    const remoteBySlug = new Map(remote.map((r) => [r.slug, r]));
+    const localSlugs = new Set(docs.map((d) => d.slug));
+    base.orfaos = remote.map((r) => r.slug).filter((s) => !localSlugs.has(s)).sort();
+    for (const d of docs) {
+        const r = remoteBySlug.get(d.slug);
+        if (sameAsRemote(d, r)) {
+            base.inalterados.push(d.slug);
+            continue;
+        }
+        if (dryRun) {
+            base.enviados.push({ slug: d.slug, visibility: d.visibility, created: !r });
+            continue;
+        }
+        let attempt = 0;
+        for (;;) {
+            await pace();
+            try {
+                const res = await apiRequest(basePath, {
+                    method: 'POST',
+                    token,
+                    body: { slug: d.slug, content: d.content, frontmatter: d.frontmatter, visibility: d.visibility },
+                    timeoutMs: 30_000,
+                });
+                if (res?.unchanged)
+                    base.inalterados.push(d.slug);
+                else
+                    base.enviados.push({ slug: d.slug, version: res?.version, created: res?.created, visibility: d.visibility });
+                break;
+            }
+            catch (err) {
+                if (isRouteMissing(err)) {
+                    return { ...base, status: 'core-sem-suporte', message: 'O Core ainda não aceita docs de produto (a publicação não existe). Os docs continuam no repositório.' };
+                }
+                const status = err instanceof CliApiError ? err.status : 0;
+                if ((status === 429 || status === 503) && attempt < MAX_RETRIES) {
+                    attempt++;
+                    const ra = err.retryAfterSeconds;
+                    const waitS = Math.min(MAX_RETRY_AFTER_S, ra !== undefined ? Math.max(1, ra) : DEFAULT_RETRY_AFTER_S * attempt);
+                    opts.onWait?.(waitS * 1000, 'retry-after');
+                    await sleep(waitS * 1000);
+                    continue;
+                }
+                const msg = err instanceof Error ? err.message : String(err);
+                base.falhas.push({
+                    slug: d.slug,
+                    message: status === 413 ? `grande demais para o Core (${msg})` : status === 429 ? `limite de envios do Core (${msg}) — tente de novo em alguns minutos` : msg,
+                });
+                break;
+            }
+        }
+    }
+    if (base.falhas.length) {
+        return { ...base, status: 'parcial', message: `${base.enviados.length} enviado(s), ${base.falhas.length} com falha.` };
+    }
+    return {
+        ...base,
+        status: 'ok',
+        message: dryRun
+            ? `Simulação: ${base.enviados.length} doc(s) seriam enviados, ${base.inalterados.length} sem mudança.`
+            : `${base.enviados.length} doc(s) enviados, ${base.inalterados.length} sem mudança.`,
+    };
+}
+//# sourceMappingURL=sync.js.map

package/dist/lib/product-docs/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../src/lib/product-docs/sync.ts"],"names":[],"mappings":"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"}

package/dist/lib/product-docs/taxonomy.d.ts

@@ -0,0 +1,46 @@
+export type DocFamily = 'vivo' | 'plano' | 'registro';
+export interface DocsTaxonomy {
+    protocolVersion: number;
+    categories: Record<string, string[]>;
+    productOnlyCategories: Record<string, string[]>;
+    coreOnlyCategories: string[];
+    types: Record<string, DocFamily>;
+    statusByFamily: Record<DocFamily, string[]>;
+    statusByTypeOverride: Record<string, string[]>;
+    audiences: string[];
+    owners: string[];
+    hiddenDirs: string[];
+}
+/** Bloco §5.2 do protocolo da wiki, v1 (2026-10-03). NÃO editar à mão sem mudar o protocolo. */
+export declare const EMBEDDED_TAXONOMY: DocsTaxonomy;
+/** Categorias válidas num repositório de PRODUTO: as do Core menos as só-do-Core, mais as só-de-produto. */
+export declare function productCategories(t: DocsTaxonomy): Record<string, string[]>;
+/** Status aceitos para um `type` (override por tipo vence a família). */
+export declare function statusesForType(t: DocsTaxonomy, type: string): string[];
+/** Validação mínima do formato EMBUTIDO (categorias como mapa categoria → subcategorias). */
+export declare function isValidTaxonomy(x: unknown): x is DocsTaxonomy;
+/**
+ * Converte a taxonomia vinda do Core para o formato da CLI. Aceita os dois:
+ *   - o do Core (`src/lib/docs-taxonomy.json`, servido por
+ *     `GET /api/cli/v1/docs/taxonomy`): `categories` é a LISTA de nomes (ordem do
+ *     portal) e `subcategories` é o mapa categoria → subcategorias, com chaves
+ *     extras (`subcategoryLabels`, `folders`, `legacyCategories`…) ignoradas;
+ *   - o embutido (`categories` já como mapa).
+ * Devolve null quando o formato não serve — quem chama cai no embutido.
+ */
+export declare function normalizeTaxonomy(x: unknown): DocsTaxonomy | null;
+export interface ResolvedTaxonomy {
+    taxonomy: DocsTaxonomy;
+    source: 'core' | 'embutida';
+    /** Preenchido quando a do Core é mais nova que a embutida (atualize a CLI). */
+    aviso?: string;
+}
+/**
+ * Taxonomia a usar: a do Core quando online (`GET /api/cli/v1/docs/taxonomy`),
+ * senão a embutida. Nunca lança — offline, 404, timeout ou formato inválido
+ * caem silenciosamente na embutida.
+ */
+export declare function resolveTaxonomy(opts?: {
+    offline?: boolean;
+    timeoutMs?: number;
+}): Promise<ResolvedTaxonomy>;

package/dist/lib/product-docs/taxonomy.js

@@ -0,0 +1,163 @@
+/**
+ * Taxonomia dos docs (protocolo v1) — cópia EMBUTIDA na CLI.
+ *
+ * Fonte única: `src/lib/docs-taxonomy.json` no Core, que por sua vez copia o
+ * bloco JSON do §5.2 de `docs/sistema/contrib/PROTOCOLO_WIKI_INTERNA.md`.
+ * O teste `product-docs-taxonomy.test.ts` confere que este objeto é IDÊNTICO
+ * ao bloco do protocolo (fixture `__tests__/fixtures/docs-taxonomy-protocolo-v1.json`
+ * e, quando há um checkout do Core por perto, o próprio markdown).
+ *
+ * Quando o Core expõe `GET /api/cli/v1/docs/taxonomy`, `resolveTaxonomy()` usa
+ * a versão do Core (online) e cai nesta cópia em qualquer falha (offline, 404,
+ * formato inesperado). Avisa quando a do Core é mais nova que a embutida.
+ */
+import { apiRequest } from '../api-client.js';
+/** Bloco §5.2 do protocolo da wiki, v1 (2026-10-03). NÃO editar à mão sem mudar o protocolo. */
+export const EMBEDDED_TAXONOMY = {
+    protocolVersion: 1,
+    categories: {
+        Plataforma: ['visao-geral', 'decisoes', 'roadmap', 'versionamento', 'modulos', 'superficies-publicas', 'portal-do-cliente'],
+        Identidade: ['login-staff', 'mfa', 'oidc', 'contas-de-cliente', 'permissoes', 'chaves-de-api'],
+        'Cobrança': ['stripe', 'assinaturas', 'faturas-e-receita', 'inadimplencia', 'uso-medido', 'precos', 'filiados'],
+        Dados: ['firestore', 'bancos-de-produto', 'migracoes', 'backup-e-recuperacao', 'regras-e-indices', 'trilha-de-auditoria'],
+        Infraestrutura: ['vm-e-frota', 'agente', 'servicos-na-vm', 'ambientes', 'cloud-functions', 'cloud-run', 'dns-e-certificados', 'gcp-e-contas'],
+        Observabilidade: ['logs', 'metricas', 'alertas', 'erros', 'rastreamento', 'incidentes'],
+        'Segurança': ['segredos', 'controle-de-acesso', 'privacidade-e-lgpd', 'vulnerabilidades', 'configuracao-segura'],
+        'Operações': ['deploy-do-core', 'producao', 'custos', 'suporte', 'comunicacao-interna', 'integracoes-externas'],
+        'Produtos SaaS': ['do-zero-a-producao', 'ciclo-de-vida', 'deploy-de-produto', 'api-de-produto', 'credenciais', 'documentacao-de-produto', 'produto-especifico'],
+        CLI: ['comandos', 'guias', 'instalacao-e-versoes'],
+        SDK: ['namespaces', 'guias', 'versoes-e-migracao'],
+        API: ['rest-v1', 'cli-v1', 'openapi', 'webhooks'],
+        Bibliotecas: ['libs-internas', 'skills', 'publicacao'],
+        Desenvolvimento: ['fluxo-git', 'qualidade-e-testes', 'ambiente-local', 'convencoes', 'interface', 'tours', 'agentes-de-ia'],
+        Empresa: ['marca', 'juridico', 'marketing', 'governanca', 'comercial', 'pessoas'],
+        'Documentação': ['indices', 'protocolos', 'inventarios', 'relatorios-automaticos'],
+    },
+    productOnlyCategories: {
+        Produto: ['visao', 'publico-e-proposta', 'roadmap', 'glossario'],
+        'Ajuda ao usuário': ['primeiros-passos', 'tarefas', 'perguntas-frequentes'],
+        'Integrações': ['marketplaces', 'pagamentos', 'fiscal', 'mensageria', 'outras'],
+    },
+    coreOnlyCategories: ['Produtos SaaS', 'CLI', 'SDK', 'Bibliotecas'],
+    types: {
+        guia: 'vivo', referencia: 'vivo', arquitetura: 'vivo', adr: 'vivo', runbook: 'vivo',
+        norma: 'vivo', indice: 'vivo', tour: 'vivo', juridico: 'vivo', conteudo: 'vivo',
+        changelog: 'vivo', plano: 'plano', relatorio: 'registro', incidente: 'registro', ata: 'registro',
+    },
+    statusByFamily: {
+        vivo: ['draft', 'active', 'deprecated', 'superseded', 'archived'],
+        plano: ['draft', 'proposed', 'in_progress', 'deferred', 'done', 'abandoned', 'superseded', 'archived'],
+        registro: ['draft', 'historical', 'superseded', 'archived'],
+    },
+    statusByTypeOverride: {
+        adr: ['proposed', 'active', 'deprecated', 'superseded', 'archived'],
+    },
+    audiences: ['staff', 'dev-produto', 'publico'],
+    owners: ['dev-core', 'operacoes', 'seguranca', 'produto', 'marca-e-marketing', 'juridico', 'diretoria', 'documentacao'],
+    hiddenDirs: ['.git', 'node_modules', '.obsidian', 'tours', '_brand', '_archive', '_assets', '_audit', '_diagrams', '_projetos', '_review', '_inventario', 'reunioes', 'features', 'legal', 'marketing', 'superpowers'],
+};
+/** Categorias válidas num repositório de PRODUTO: as do Core menos as só-do-Core, mais as só-de-produto. */
+export function productCategories(t) {
+    const out = {};
+    for (const [cat, subs] of Object.entries(t.categories)) {
+        if (!t.coreOnlyCategories.includes(cat))
+            out[cat] = subs;
+    }
+    for (const [cat, subs] of Object.entries(t.productOnlyCategories))
+        out[cat] = subs;
+    return out;
+}
+/** Status aceitos para um `type` (override por tipo vence a família). */
+export function statusesForType(t, type) {
+    const override = t.statusByTypeOverride[type];
+    if (override)
+        return override;
+    const fam = t.types[type];
+    return fam ? t.statusByFamily[fam] ?? [] : [];
+}
+const isRecordOfArrays = (r) => !!r && typeof r === 'object' && !Array.isArray(r) && Object.values(r).every((v) => Array.isArray(v));
+/** Validação mínima do formato EMBUTIDO (categorias como mapa categoria → subcategorias). */
+export function isValidTaxonomy(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const t = x;
+    return (typeof t.protocolVersion === 'number' &&
+        isRecordOfArrays(t.categories) &&
+        isRecordOfArrays(t.productOnlyCategories) &&
+        Array.isArray(t.coreOnlyCategories) &&
+        !!t.types && typeof t.types === 'object' &&
+        isRecordOfArrays(t.statusByFamily) &&
+        Array.isArray(t.audiences) &&
+        Array.isArray(t.owners));
+}
+/**
+ * Converte a taxonomia vinda do Core para o formato da CLI. Aceita os dois:
+ *   - o do Core (`src/lib/docs-taxonomy.json`, servido por
+ *     `GET /api/cli/v1/docs/taxonomy`): `categories` é a LISTA de nomes (ordem do
+ *     portal) e `subcategories` é o mapa categoria → subcategorias, com chaves
+ *     extras (`subcategoryLabels`, `folders`, `legacyCategories`…) ignoradas;
+ *   - o embutido (`categories` já como mapa).
+ * Devolve null quando o formato não serve — quem chama cai no embutido.
+ */
+export function normalizeTaxonomy(x) {
+    if (!x || typeof x !== 'object')
+        return null;
+    const t = x;
+    let categories = null;
+    if (Array.isArray(t.categories)) {
+        if (!isRecordOfArrays(t.subcategories))
+            return null;
+        const subs = t.subcategories;
+        categories = {};
+        for (const c of t.categories) {
+            if (typeof c !== 'string' || !Array.isArray(subs[c]))
+                return null;
+            categories[c] = subs[c];
+        }
+    }
+    else if (isRecordOfArrays(t.categories)) {
+        categories = t.categories;
+    }
+    if (!categories)
+        return null;
+    const candidate = {
+        protocolVersion: t.protocolVersion,
+        categories,
+        productOnlyCategories: t.productOnlyCategories,
+        coreOnlyCategories: t.coreOnlyCategories,
+        types: t.types,
+        statusByFamily: t.statusByFamily,
+        statusByTypeOverride: isRecordOfArrays(t.statusByTypeOverride) ? t.statusByTypeOverride : {},
+        audiences: t.audiences,
+        owners: t.owners,
+        hiddenDirs: Array.isArray(t.hiddenDirs) ? t.hiddenDirs : EMBEDDED_TAXONOMY.hiddenDirs,
+    };
+    return isValidTaxonomy(candidate) ? candidate : null;
+}
+/**
+ * Taxonomia a usar: a do Core quando online (`GET /api/cli/v1/docs/taxonomy`),
+ * senão a embutida. Nunca lança — offline, 404, timeout ou formato inválido
+ * caem silenciosamente na embutida.
+ */
+export async function resolveTaxonomy(opts = {}) {
+    if (opts.offline || process.env.NEETRU_DOCS_OFFLINE === '1') {
+        return { taxonomy: EMBEDDED_TAXONOMY, source: 'embutida' };
+    }
+    try {
+        const res = await apiRequest('/api/cli/v1/docs/taxonomy', { timeoutMs: opts.timeoutMs ?? 3000 });
+        const body = res;
+        const candidate = body && typeof body === 'object' && 'taxonomy' in body ? body.taxonomy : res;
+        const normalized = normalizeTaxonomy(candidate);
+        if (!normalized)
+            return { taxonomy: EMBEDDED_TAXONOMY, source: 'embutida' };
+        const aviso = normalized.protocolVersion > EMBEDDED_TAXONOMY.protocolVersion
+            ? `A taxonomia do Core é a versão ${normalized.protocolVersion} e a desta CLI é a ${EMBEDDED_TAXONOMY.protocolVersion}. ` +
+                'Usando a do Core agora; atualize a CLI (npm i -g @neetru/cli) para checar offline com a versão nova.'
+            : undefined;
+        return { taxonomy: normalized, source: 'core', aviso };
+    }
+    catch {
+        return { taxonomy: EMBEDDED_TAXONOMY, source: 'embutida' };
+    }
+}
+//# sourceMappingURL=taxonomy.js.map

package/dist/lib/product-docs/taxonomy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"taxonomy.js","sourceRoot":"","sources":["../../../src/lib/product-docs/taxonomy.ts"],"names":[],"mappings":"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"}

package/dist/lib/product-docs/templates.d.ts

@@ -0,0 +1,53 @@
+import { THREAT_MODEL_SECTIONS, type Section } from './structure.js';
+export interface DocSpec {
+    title: string;
+    description: string;
+    product: string;
+    category: string;
+    subcategory: string;
+    type: string;
+    status: string;
+    date: string;
+    /** Só na família vivo. */
+    updated?: string;
+    audience: string;
+    owner?: string;
+    adr?: number;
+    order?: number;
+    /** Abertura logo abaixo do H1 (até 3 linhas). */
+    lead: string;
+    sections: Section[];
+    /** Conteúdo extra por seção (vai depois do comentário). */
+    extra?: Record<string, string>;
+}
+export declare function renderDoc(spec: DocSpec): string;
+export declare const ADR_EXTRA: Record<string, string>;
+export declare const PLANO_RFC_EXTRA: Record<string, string>;
+export declare const PLANO_SPEC_EXTRA: Record<string, string>;
+export declare const NORMA_POLITICA_EXTRA: Record<string, string>;
+export declare const THREAT_EXTRA: Record<string, string>;
+export { THREAT_MODEL_SECTIONS };
+export declare function renderReadme(name: string): string;
+export declare function renderChangelog(seed: {
+    version: string;
+    date: string;
+    maduro: boolean;
+}): string;
+export interface IndexGroup {
+    label: string;
+    files: Array<{
+        rel: string;
+        title: string;
+        nomeForaDaRegra?: boolean;
+    }>;
+    /** Grupo fora da estrutura do protocolo (marcado no índice). */
+    foraDoPadrao?: boolean;
+    nota?: string;
+}
+export declare function renderIndex(opts: {
+    product: string;
+    name: string;
+    today: string;
+    groups: IndexGroup[];
+}): string;
+export declare const FOLDER_LABEL: Record<string, string>;