@neetru/cli 2.29.0 → 2.32.0

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

@@ -0,0 +1,61 @@
+/**
+ * Estrutura do `docs/` de um produto SaaS (PROTOCOLO_DOCS_PRODUTOS_SAAS §3, §6, §7)
+ * e modelos por tipo (PROTOCOLO_WIKI_INTERNA §7.4, §8).
+ *
+ * Tudo aqui é dado puro — sem I/O — para o validador, o `init`, o `new` e o
+ * `--migrar` lerem da mesma tabela.
+ */
+export interface FolderRule {
+    /** Pasta de primeiro nível dentro de `docs/` ('' = a raiz de `docs/`). */
+    folder: string;
+    types: string[] | 'qualquer';
+    category: string;
+    subcategory: string;
+    audience: 'dev-produto' | 'publico' | 'staff';
+    idade: 'corrente' | 'intermediaria' | 'permanente' | 'gerada';
+}
+/**
+ * §3 do protocolo de produtos. `category/subcategory` são o PADRÃO da pasta
+ * (o protocolo diz "a do assunto" em várias — o padrão é só o ponto de partida).
+ */
+export declare const FOLDER_RULES: FolderRule[];
+/** Pastas do §3 que o `docs init` cria. */
+export declare const STANDARD_FOLDERS: string[];
+/** Pastas que o validador não visita. `_audit/` é saída de script (só FM001). */
+export declare const SKIP_DIRS: Set<string>;
+/** Primeira pasta de um caminho relativo a `docs/` ('' para a raiz). */
+export declare function topFolder(relPath: string): string;
+export declare function folderRule(relPath: string): FolderRule | undefined;
+export interface DayOneItem {
+    /** Caminho relativo à RAIZ do repositório. */
+    path: string;
+    /** Obrigatório só quando o produto expõe /api/v1. */
+    soComApi?: boolean;
+}
+export declare const DAY_ONE: DayOneItem[];
+/** "No primeiro mês" (recomendado; o validador só sugere). */
+export declare const FIRST_MONTH: string[];
+/** Seções que o README da raiz precisa ter (§7) — casamento tolerante. */
+export declare const README_SECTIONS: Array<{
+    label: string;
+    match: RegExp;
+}>;
+export interface Section {
+    title: string;
+    required: boolean;
+    /** Orientação que vira `<!-- … -->` dentro da seção. */
+    hint: string;
+}
+export declare const TYPE_MODELS: Record<string, Section[]>;
+/** Modelo de ameaças (base: `neetru-zelo/docs/design/modelos/threat-model.md`) — um `referencia` em `seguranca/`. */
+export declare const THREAT_MODEL_SECTIONS: Section[];
+/** Seções obrigatórias dos docs do mínimo do primeiro dia (§7.2), por caminho relativo a `docs/`. */
+export declare const DAY_ONE_MODELS: Record<string, Section[]>;
+export declare const FILE_NAME_REGEX: RegExp;
+/** Prefixo de nome por tipo (doc novo). `referencia` não tem prefixo obrigatório. */
+export declare const TYPE_PREFIX: Record<string, string>;
+/** Pasta onde `docs new <tipo>` cria o doc, quando a categoria não decide. */
+export declare const TYPE_DEFAULT_FOLDER: Record<string, string>;
+/** Pasta preferida por categoria (quando o tipo cabe nela). */
+export declare const CATEGORY_FOLDER: Record<string, string>;
+export declare const STOPWORDS: Set<string>;

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

@@ -0,0 +1,239 @@
+/**
+ * Estrutura do `docs/` de um produto SaaS (PROTOCOLO_DOCS_PRODUTOS_SAAS §3, §6, §7)
+ * e modelos por tipo (PROTOCOLO_WIKI_INTERNA §7.4, §8).
+ *
+ * Tudo aqui é dado puro — sem I/O — para o validador, o `init`, o `new` e o
+ * `--migrar` lerem da mesma tabela.
+ */
+/**
+ * §3 do protocolo de produtos. `category/subcategory` são o PADRÃO da pasta
+ * (o protocolo diz "a do assunto" em várias — o padrão é só o ponto de partida).
+ */
+export const FOLDER_RULES = [
+    // raiz: `index.md`. `changelog` também é aceito aqui (tipo próprio de produto, §4).
+    { folder: '', types: ['indice', 'changelog'], category: 'Documentação', subcategory: 'indices', audience: 'dev-produto', idade: 'corrente' },
+    { folder: 'produto', types: ['referencia', 'plano'], category: 'Produto', subcategory: 'visao', audience: 'dev-produto', idade: 'corrente' },
+    { folder: 'arquitetura', types: ['arquitetura', 'referencia'], category: 'Plataforma', subcategory: 'visao-geral', audience: 'dev-produto', idade: 'corrente' },
+    { folder: 'api', types: ['referencia'], category: 'API', subcategory: 'rest-v1', audience: 'dev-produto', idade: 'corrente' },
+    { folder: 'decisoes', types: ['adr'], category: 'Plataforma', subcategory: 'decisoes', audience: 'dev-produto', idade: 'corrente' },
+    { folder: 'runbooks', types: ['runbook'], category: 'Operações', subcategory: 'producao', audience: 'dev-produto', idade: 'corrente' },
+    { folder: 'guias', types: ['guia'], category: 'Desenvolvimento', subcategory: 'ambiente-local', audience: 'dev-produto', idade: 'corrente' },
+    { folder: 'integracoes', types: ['referencia', 'guia'], category: 'Integrações', subcategory: 'outras', audience: 'dev-produto', idade: 'corrente' },
+    { folder: 'seguranca', types: ['norma', 'referencia'], category: 'Segurança', subcategory: 'configuracao-segura', audience: 'dev-produto', idade: 'corrente' },
+    { folder: 'usuario', types: ['guia', 'referencia'], category: 'Ajuda ao usuário', subcategory: 'tarefas', audience: 'publico', idade: 'corrente' },
+    { folder: 'planos', types: ['plano'], category: 'Plataforma', subcategory: 'roadmap', audience: 'dev-produto', idade: 'intermediaria' },
+    { folder: 'superpowers', types: ['plano'], category: 'Plataforma', subcategory: 'roadmap', audience: 'dev-produto', idade: 'intermediaria' },
+    { folder: 'relatorios', types: ['relatorio', 'incidente', 'ata'], category: 'Plataforma', subcategory: 'visao-geral', audience: 'dev-produto', idade: 'intermediaria' },
+    { folder: '_archive', types: 'qualquer', category: 'Plataforma', subcategory: 'visao-geral', audience: 'dev-produto', idade: 'permanente' },
+];
+/** Pastas do §3 que o `docs init` cria. */
+export const STANDARD_FOLDERS = [
+    'produto', 'arquitetura', 'api', 'decisoes', 'runbooks', 'guias', 'integracoes',
+    'seguranca', 'usuario', 'planos', 'relatorios', '_archive',
+];
+/** Pastas que o validador não visita. `_audit/` é saída de script (só FM001). */
+export const SKIP_DIRS = new Set(['.git', 'node_modules', '.obsidian', '_assets', '_brand', '_diagrams']);
+/** Primeira pasta de um caminho relativo a `docs/` ('' para a raiz). */
+export function topFolder(relPath) {
+    const parts = relPath.replace(/\\/g, '/').split('/');
+    return parts.length > 1 ? parts[0] : '';
+}
+export function folderRule(relPath) {
+    const top = topFolder(relPath);
+    return FOLDER_RULES.find((r) => r.folder === top);
+}
+export const DAY_ONE = [
+    { path: 'README.md' },
+    { path: 'CHANGELOG.md' },
+    { path: 'docs/index.md' },
+    { path: 'docs/produto/VISAO_DO_PRODUTO.md' },
+    { path: 'docs/arquitetura/ARQUITETURA.md' },
+    { path: 'docs/runbooks/RUNBOOK_DEPLOY.md' },
+    { path: 'docs/api/API_V1.md', soComApi: true },
+];
+/** "No primeiro mês" (recomendado; o validador só sugere). */
+export const FIRST_MONTH = [
+    'docs/arquitetura/MODELO_DE_DADOS.md',
+    'docs/runbooks/RUNBOOK_INCIDENTES.md',
+    'docs/produto/GLOSSARIO.md',
+    'docs/guias/GUIA_DESENVOLVIMENTO_LOCAL.md',
+];
+/** Seções que o README da raiz precisa ter (§7) — casamento tolerante. */
+export const README_SECTIONS = [
+    { label: 'O que é', match: /o que (e|é)|sobre/i },
+    { label: 'Como rodar local', match: /rodar|local|desenvolv/i },
+    { label: 'Como fazer deploy', match: /deploy|publica/i },
+];
+const s = (title, required, hint) => ({ title, required, hint });
+export const TYPE_MODELS = {
+    runbook: [
+        s('Quando usar', true, 'Em que situação este procedimento é executado e o que ele resolve.'),
+        s('Pré-requisitos', false, 'Acessos, ferramentas e estado que precisam existir antes de começar.'),
+        s('Passo a passo', true, 'Passos numerados e verificáveis, com o comando exato de cada um.'),
+        s('Verificação', true, 'Como provar que deu certo (comando, URL, resultado esperado).'),
+        s('Como desfazer', false, 'Como voltar ao estado anterior se algo der errado.'),
+        s('Problemas comuns', false, 'Sintoma, causa e correção dos erros que já apareceram.'),
+        s('Relacionados', false, 'Links relativos (com .md) para docs próximos.'),
+    ],
+    guia: [
+        s('Objetivo', true, 'O que a pessoa consegue fazer ao fim do guia.'),
+        s('Pré-requisitos', false, 'O que precisa estar pronto antes.'),
+        s('Passo a passo', false, 'Passos em ordem, ou uma seção por tarefa.'),
+        s('Problemas comuns', false, 'Erros frequentes e como resolver.'),
+        s('Relacionados', false, 'Links relativos (com .md) para docs próximos.'),
+    ],
+    referencia: [
+        s('Visão geral', true, 'O que esta referência lista e como ler.'),
+        s('Exemplos', false, 'Exemplos reais de uso.'),
+        s('Relacionados', false, 'Links relativos (com .md) para docs próximos.'),
+    ],
+    arquitetura: [
+        s('Contexto', true, 'Que problema esta parte resolve e que restrições pesam.'),
+        s('Visão geral', true, 'O desenho em poucas linhas e, se ajudar, um diagrama.'),
+        s('Componentes', false, 'As peças, o papel de cada uma e onde moram no código.'),
+        s('Fluxos', false, 'Os caminhos principais de ponta a ponta.'),
+        s('Decisões e alternativas', false, 'Por que foi desenhado assim; aponte os ADRs.'),
+        s('Limites e riscos', false, 'O que não cobre, limites conhecidos e riscos.'),
+        s('Relacionados', false, 'Links relativos (com .md) para docs próximos.'),
+    ],
+    adr: [
+        s('Contexto', true, 'O que força a decisão: restrições, contrato, limite, fase. Só fatos.'),
+        s('Decisão', true, 'A opção escolhida e o motivo em 1 a 3 linhas. Diga também o que NÃO está decidido.'),
+        s('Alternativas consideradas', false, 'Uma H3 por opção ("### Opção A — <nome>") com prós, contras, custo/risco e o trade-off.'),
+        s('Consequências', true, 'Positivas; negativas e dívida assumida; como reverter; onde a decisão passa a viver (código, contrato da API, arquitetura). Se houver, a rastreabilidade: requisito, teste que prova, status.'),
+        s('Referências', false, 'Links relativos (com .md), PRs e commits.'),
+    ],
+    norma: [
+        s('Objetivo', true, 'Que risco ou bagunça esta norma evita.'),
+        s('Escopo', false, 'Onde vale e onde não vale.'),
+        s('Regras', true, 'Regras numeradas e verificáveis. Para uma ação ou política: nome, o que faz, se é reversível, privilégio, parâmetros tipados e validados (nada de texto livre que vire comando), quando dispara e o modo padrão (sugerir; agir é opt-in).'),
+        s('Como é verificado', false, 'Teste, validador ou revisão que prova o cumprimento. Inclua os critérios de aceite (fora da lista → recusado; parâmetro inválido → recusado antes de executar).'),
+        s('Exceções', false, 'Exceções aceitas, cada uma com motivo.'),
+        s('Histórico de mudanças', false, 'Versão, data e mudança.'),
+    ],
+    plano: [
+        s('Resumo', true, 'Um parágrafo: o que muda e por quê.'),
+        s('Problema', false, 'Sintoma observável, sem citar a solução.'),
+        s('Proposta', true, 'Fluxo, contrato (entradas, saídas, erros, idempotência), estados e transições, dados que trafegam e o impacto por frente.'),
+        s('Fora de escopo', false, 'O que este plano não faz.'),
+        s('Fases e critérios de aceite', false, 'Fases, rollout e rollback, e critérios verificáveis (teste, contrato, smoke).'),
+        s('Riscos', false, 'Casos de borda (offline, credencial inválida, concorrência, dado velho), privacidade e segurança.'),
+        s('Decisões pendentes', false, 'O que depende do dono ou do Core, com opções.'),
+        s('Status e evidência', false, 'Estado atual com evidência (arquivo:linha, commit, PR).'),
+    ],
+    relatorio: [
+        s('Resumo', true, 'O que foi olhado e a conclusão em poucas linhas.'),
+        s('Escopo e método', false, 'O que entrou, o que ficou de fora e como foi feito.'),
+        s('Achados', true, 'Por severidade: crítico, alto, médio, baixo. Cada achado com evidência.'),
+        s('Recomendações', false, 'O que fazer, em ordem de prioridade.'),
+        s('Decisões do dono', false, 'O que precisa de decisão.'),
+        s('Evidências', false, 'Comandos, saídas, links.'),
+    ],
+    incidente: [
+        s('Resumo', true, 'O que quebrou, em uma frase.'),
+        s('Impacto', true, 'Quem foi afetado, por quanto tempo, o que deixou de funcionar.'),
+        s('Linha do tempo', true, 'Horários (com fuso) do início, da detecção, da mitigação e do fim.'),
+        s('Causa raiz', true, 'A causa confirmada, com evidência — hipótese não é diagnóstico.'),
+        s('Correção', false, 'O que foi feito para resolver.'),
+        s('Ações de prevenção', false, 'O que muda para não repetir, com responsável.'),
+        s('Evidências', false, 'Logs, comandos, PRs.'),
+    ],
+    ata: [
+        s('Participantes', false, 'Quem esteve.'),
+        s('Pauta', false, 'Os assuntos.'),
+        s('Discussão', false, 'O que foi discutido.'),
+        s('Decisões', true, 'O que foi decidido.'),
+        s('Encaminhamentos', true, 'Cada um com responsável e prazo.'),
+    ],
+    juridico: [
+        s('Objeto', true, 'Do que trata o texto.'),
+        s('Vigência e versão', true, 'Desde quando vale e qual versão é.'),
+        s('Onde é publicado', false, 'Página ou superfície onde aparece.'),
+    ],
+    conteudo: [
+        s('Objetivo', true, 'Para que serve a peça.'),
+        s('Público', false, 'Para quem.'),
+        s('Peças', false, 'As peças.'),
+        s('Aprovação', false, 'Quem aprovou e quando.'),
+    ],
+    indice: [],
+    tour: [],
+    changelog: [],
+};
+/** Modelo de ameaças (base: `neetru-zelo/docs/design/modelos/threat-model.md`) — um `referencia` em `seguranca/`. */
+export const THREAT_MODEL_SECTIONS = [
+    s('Visão geral', true, 'Superfície analisada (login, comando, credencial, transporte…), versão do desenho e data.'),
+    s('Ativos', true, 'Ativos (credencial, canal de comando, binário, dados) e fronteiras de confiança: navegador │ rede │ produto │ Core. O que cruza cada fronteira.'),
+    s('Ameaças', true, 'Tabela STRIDE: #, categoria (falsificação, adulteração, repúdio, vazamento, negação de serviço, elevação de privilégio), ameaça, como exploraria, impacto, probabilidade, risco.'),
+    s('Mitigações', true, 'Tabela: #, mitigação, tipo (prevenir/detectar/responder), onde implementa, se é regra dura.'),
+    s('Riscos aceitos', true, 'O que fica em aberto, por quê e quem é o dono do risco.'),
+    s('Relacionados', false, 'Como a mitigação é provada (teste, revisão) e os ADRs derivados.'),
+];
+/** Seções obrigatórias dos docs do mínimo do primeiro dia (§7.2), por caminho relativo a `docs/`. */
+export const DAY_ONE_MODELS = {
+    'produto/VISAO_DO_PRODUTO.md': [
+        s('Problema que resolve', true, 'A dor do cliente, com exemplo concreto. Sem métrica inventada.'),
+        s('Para quem', true, 'Quem usa (perfil de empresa e de pessoa) e quem decide a compra.'),
+        s('O que o produto faz', true, 'As capacidades principais, em linguagem do cliente.'),
+        s('O que não faz', false, 'Limites claros, para não prometer o que não existe.'),
+        s('Como se mede o resultado', false, 'Só métricas reais, com a fonte.'),
+        s('Relacionados', false, 'Links relativos (com .md).'),
+    ],
+    'arquitetura/ARQUITETURA.md': [
+        s('Contexto', true, 'O que o produto é tecnicamente e que restrições pesam.'),
+        s('Visão geral', true, 'O desenho em poucas linhas: front, servidor, banco, integrações.'),
+        s('Componentes', false, 'As peças, o papel de cada uma e onde moram no código.'),
+        s('Integração com o Core', true, 'SDK @neetru/sdk como ÚNICO caminho de dados; login OIDC do Core; banco por produto provisionado pelo Core; credenciais injetadas no servidor (nunca no navegador, nunca em .env versionado); ambientes dev → homologação → produção.'),
+        s('Dados', false, 'Entidades principais e onde ficam; aponte o MODELO_DE_DADOS.md quando existir.'),
+        s('Limites e riscos', false, 'Limites conhecidos e riscos.'),
+        s('Relacionados', false, 'Links relativos (com .md).'),
+    ],
+    'api/API_V1.md': [
+        s('Base e autenticação', true, 'Base https://<produto>.neetru.com/api/v1. Authorization: Bearer com token OIDC no app, cookie de sessão na web. O tenant vem sempre do servidor, nunca do corpo.'),
+        s('Formato de erro', true, 'Sempre {"error":{"code","message","requestId"}}. Liste os códigos.'),
+        s('Idempotência', false, 'Idempotency-Key obrigatório em escrita que mexe com dinheiro ou estoque.'),
+        s('Limites de uso', false, '429 com Retry-After; os limites por rota.'),
+        s('Paginação, datas e dinheiro', false, 'Paginação por cursor, datas em ISO UTC, dinheiro em centavos.'),
+        s('Versionamento', true, 'A v1 só ganha campos; o que quebra vai para /api/v2. Se o produto foge da convenção, diga onde e por quê.'),
+        s('Endpoints', true, 'Uma H3 por endpoint (ex.: "### GET /api/v1/me") com autenticação, corpo, respostas, erros e exemplo.'),
+    ],
+    'runbooks/RUNBOOK_DEPLOY.md': TYPE_MODELS.runbook,
+};
+// ─── nomes de arquivo (§8 da wiki, §6 de produtos) ──────────────────────────
+export const FILE_NAME_REGEX = /^(ADR-\d{4}_[A-Z0-9]+(_[A-Z0-9]+)*|[A-Z][A-Z0-9]*(_[A-Z0-9]+)*(_\d{4}-\d{2}(-\d{2})?)?)\.md$/;
+/** Prefixo de nome por tipo (doc novo). `referencia` não tem prefixo obrigatório. */
+export const TYPE_PREFIX = {
+    runbook: 'RUNBOOK',
+    guia: 'GUIA',
+    arquitetura: 'ARQUITETURA',
+    norma: 'POLITICA',
+    plano: 'PLANO',
+    relatorio: 'RELATORIO',
+    incidente: 'INCIDENTE',
+    ata: 'ATA',
+    referencia: '',
+    adr: 'ADR',
+};
+/** Pasta onde `docs new <tipo>` cria o doc, quando a categoria não decide. */
+export const TYPE_DEFAULT_FOLDER = {
+    guia: 'guias',
+    referencia: 'arquitetura',
+    arquitetura: 'arquitetura',
+    adr: 'decisoes',
+    runbook: 'runbooks',
+    norma: 'seguranca',
+    plano: 'planos',
+    relatorio: 'relatorios',
+    incidente: 'relatorios',
+    ata: 'relatorios',
+};
+/** Pasta preferida por categoria (quando o tipo cabe nela). */
+export const CATEGORY_FOLDER = {
+    Produto: 'produto',
+    'Ajuda ao usuário': 'usuario',
+    'Integrações': 'integracoes',
+    'Segurança': 'seguranca',
+    API: 'api',
+};
+export const STOPWORDS = new Set(['DE', 'DA', 'DO', 'DAS', 'DOS', 'E', 'O', 'A', 'OS', 'AS', 'EM', 'NO', 'NA', 'NOS', 'NAS', 'PARA', 'POR', 'COM', 'UM', 'UMA']);
+//# sourceMappingURL=structure.js.map

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

@@ -0,0 +1,107 @@
+import { type FmData } from './frontmatter.js';
+import type { DocsTaxonomy } from './taxonomy.js';
+import type { ProductRepo } from './config.js';
+export declare const MAX_PRODUCT_DOCS = 200;
+export declare const MAX_PRODUCT_DOCS_BYTES: number;
+/** Teto por doc no Core (`MAX_PRODUCT_DOC_BYTES`, 413 `doc_too_large`). */
+export declare const MAX_PRODUCT_DOC_BYTES: number;
+/** Abaixo do `cliWrite` do Core (30/min por IP), com folga para outro comando na mesma rede. */
+export declare const POSTS_PER_MINUTE = 25;
+/** Tentativas extras quando o Core responde 429/503. */
+export declare const MAX_RETRIES = 3;
+export type SyncStatus = 'ok' | 'parcial' | 'nada-a-enviar' | 'core-sem-suporte' | 'desligado' | 'sem-login' | 'limite-excedido' | 'produto-nao-encontrado' | 'falha';
+export interface RemoteDoc {
+    slug: string;
+    title?: string | null;
+    description?: string | null;
+    category?: string | null;
+    subcategory?: string | null;
+    type?: string | null;
+    status?: string | null;
+    audience?: string | null;
+    order?: number | null;
+    updated?: string | null;
+    date?: string | null;
+    visibility?: string;
+    sha256?: string;
+    version?: number;
+}
+/** Metadados que o GET do Core devolve e que a CLI compara (o que vier). */
+export declare const COMPARED_METADATA: readonly ["title", "description", "category", "subcategory", "type", "status", "audience", "order", "updated", "date"];
+export interface LocalDoc {
+    file: string;
+    slug: string;
+    content: string;
+    frontmatter: FmData;
+    visibility: 'public' | 'internal';
+    sha256: string;
+    bytes: number;
+}
+export interface SyncResult {
+    status: SyncStatus;
+    message: string;
+    product: string;
+    dryRun: boolean;
+    enviados: Array<{
+        slug: string;
+        version?: number;
+        created?: boolean;
+        visibility: string;
+    }>;
+    inalterados: string[];
+    bloqueados: Array<{
+        file: string;
+        codes: string[];
+    }>;
+    /**
+     * Docs que o Core recusou. `httpStatus` é o status da resposta (0 = sem
+     * resposta HTTP: rede, timeout) — é dele que sai o código de saída de cada
+     * falha no `neetru docs sync` (P105).
+     */
+    falhas: Array<{
+        slug: string;
+        message: string;
+        httpStatus: number;
+    }>;
+    /** Não enviados por regra do Core conferida localmente (slug, tamanho). */
+    recusados: Array<{
+        file: string;
+        motivo: string;
+    }>;
+    orfaos: string[];
+    /** Plano local (dry-run sem login / antes do envio). */
+    planejados: Array<{
+        slug: string;
+        visibility: string;
+        bytes: number;
+    }>;
+}
+export declare function visibilityFor(fm: FmData): 'public' | 'internal';
+export declare function docSlugFor(relInDocs: string): string;
+/**
+ * Motivo pelo qual o Core recusaria o slug (mesmas regras de
+ * `productDocSlugSchema`), ou null se ele passa.
+ */
+export declare function slugProblem(slug: string): string | null;
+/** Monta o lote local (sem I/O de rede). */
+export declare function collectLocalDocs(repo: ProductRepo, taxonomy: DocsTaxonomy): Promise<{
+    docs: LocalDoc[];
+    bloqueados: SyncResult['bloqueados'];
+    recusados: SyncResult['recusados'];
+}>;
+export interface SyncOptions {
+    taxonomy: DocsTaxonomy;
+    dryRun?: boolean;
+    /** Token já resolvido (teste/deploy); senão lê a sessão. */
+    token?: string | null;
+    /** Relógio e espera injetáveis (teste). */
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    /** Chamado antes de cada espera (para mostrar "aguardando…"). */
+    onWait?: (ms: number, motivo: 'ritmo' | 'retry-after') => void;
+}
+/** O doc local é igual ao do Core (conteúdo + metadados que o GET devolve)? */
+export declare function sameAsRemote(d: LocalDoc, r: RemoteDoc | undefined): boolean;
+/** Janela deslizante: no máximo `limit` envios em 60 s. */
+export declare function createPacer(limit: number, now: () => number, sleep: (ms: number) => Promise<void>, onWait?: SyncOptions['onWait']): () => Promise<void>;
+export declare function syncProductDocs(repo: ProductRepo, opts: SyncOptions): Promise<SyncResult>;