@neetru/cli 2.29.0 → 2.32.0

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

@@ -0,0 +1,234 @@
+/**
+ * Chave `docs` do `neetru.config.json` (PROTOCOLO_DOCS_PRODUTOS_SAAS §7.1 +
+ * decisão do dono 2026-10-03):
+ *
+ * ```json
+ * "docs": {
+ *   "protocolVersion": 1,
+ *   "root": "docs",
+ *   "publish": true,          // false = os docs ficam só no repositório (sync recusa)
+ *   "publishOnDeploy": false, // true = deploy de PRODUÇÃO publica os docs no fim (opt-in)
+ *   "api": false              // true = o produto expõe /api/v1 → API_V1.md vira obrigatório
+ * }
+ * ```
+ */
+import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
+import * as path from 'node:path';
+import { git } from './git.js';
+export const CONFIG_FILES = ['neetru.config.json', '.neetru.json'];
+export const DEFAULT_DOCS_CONFIG = {
+    protocolVersion: 1,
+    root: 'docs',
+    publish: true,
+    publishOnDeploy: false,
+    api: false,
+};
+export class ProductConfigMissingError extends Error {
+    constructor(cwd) {
+        super(`neetru.config.json não encontrado em ${cwd} nem nas pastas acima até a raiz do repositório git. ` +
+            'Rode `neetru init` primeiro (ou entre na pasta do produto).');
+        this.name = 'ProductConfigMissingError';
+    }
+}
+export class ProductConfigInvalidError extends Error {
+    constructor(file, why) {
+        super(`${file} inválido: ${why}`);
+        this.name = 'ProductConfigInvalidError';
+    }
+}
+function rawRoot(root) {
+    if (typeof root !== 'string' || !root.trim())
+        return undefined;
+    return root.trim().replace(/\\/g, '/');
+}
+export function normalizeDocsConfig(x) {
+    const d = (x && typeof x === 'object' ? x : {});
+    return {
+        protocolVersion: typeof d.protocolVersion === 'number' ? d.protocolVersion : DEFAULT_DOCS_CONFIG.protocolVersion,
+        root: rawRoot(d.root) ?? DEFAULT_DOCS_CONFIG.root,
+        publish: d.publish !== false,
+        publishOnDeploy: d.publishOnDeploy === true,
+        api: d.api === true,
+    };
+}
+function realDir(p) {
+    try {
+        return fsSync.realpathSync.native(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/** `child` está DENTRO de `parent` (estritamente)? */
+function isInside(child, parent) {
+    const rel = path.relative(parent, child);
+    return !!rel && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+const toPosix = (p) => p.split(path.sep).join('/');
+/**
+ * Lê o config do produto procurando `neetru.config.json` (ou `.neetru.json`)
+ * em `start` e nas pastas ACIMA até a raiz do repositório git (fora de git,
+ * só em `start`). `docs.root` é relativo ao config e pode apontar acima dele
+ * (`../../docs`), desde que fique DENTRO da raiz do repositório git — fora
+ * disso (ou caminho absoluto) é recusado.
+ * Lança `ProductConfigMissingError`/`ProductConfigInvalidError`.
+ */
+export async function loadProductRepo(start) {
+    const startDir = realDir(start);
+    const top = git(startDir, ['rev-parse', '--show-toplevel']);
+    const gitRoot = top ? realDir(top) : null;
+    const candidates = [startDir];
+    if (gitRoot && (isInside(startDir, gitRoot) || startDir === gitRoot)) {
+        let d = startDir;
+        while (d !== gitRoot) {
+            const up = path.dirname(d);
+            if (up === d)
+                break;
+            d = up;
+            candidates.push(d);
+        }
+    }
+    for (const configDir of candidates) {
+        for (const name of CONFIG_FILES) {
+            const configPath = path.join(configDir, name);
+            if (!fsSync.existsSync(configPath))
+                continue;
+            const label = toPosix(path.relative(startDir, configPath)) || name;
+            let raw;
+            try {
+                raw = JSON.parse((await fs.readFile(configPath, 'utf8')).replace(/^\uFEFF/, ''));
+            }
+            catch (e) {
+                throw new ProductConfigInvalidError(label, `JSON ilegível (${e.message})`);
+            }
+            if (!raw || typeof raw !== 'object')
+                throw new ProductConfigInvalidError(label, 'não é um objeto JSON');
+            const slug = typeof raw.slug === 'string' ? raw.slug.trim() : '';
+            if (!slug)
+                throw new ProductConfigInvalidError(label, 'falta o campo "slug"');
+            const nameField = typeof raw.name === 'string' && raw.name.trim() ? raw.name.trim() : slug;
+            const docs = normalizeDocsConfig(raw.docs);
+            // ── onde fica a pasta de docs ─────────────────────────────────────
+            const configured = rawRoot(raw.docs?.root);
+            let docsRootInferred;
+            let docsAbs;
+            if (configured) {
+                if (path.isAbsolute(configured) || /^[A-Za-z]:/.test(configured) || configured.startsWith('/')) {
+                    throw new ProductConfigInvalidError(label, `docs.root "${configured}" é caminho absoluto — use um caminho relativo ao neetru.config.json.`);
+                }
+                docsAbs = path.resolve(configDir, configured);
+            }
+            else {
+                docsAbs = path.join(configDir, 'docs');
+                // Monorepo: config numa subpasta, docs/ só na raiz do git.
+                if (!fsSync.existsSync(docsAbs) && gitRoot && gitRoot !== configDir && fsSync.existsSync(path.join(gitRoot, 'docs'))) {
+                    docsAbs = path.join(gitRoot, 'docs');
+                    docsRootInferred = toPosix(path.relative(configDir, docsAbs));
+                }
+            }
+            const boundary = gitRoot ?? configDir;
+            if (!isInside(docsAbs, boundary)) {
+                throw new ProductConfigInvalidError(label, `docs.root "${configured ?? 'docs'}" aponta para fora do ${gitRoot ? 'repositório git' : 'diretório do produto'} (${boundary}).`);
+            }
+            const cwd = isInside(docsAbs, configDir) ? configDir : boundary;
+            return {
+                cwd,
+                configDir,
+                configPath,
+                gitRoot,
+                raw,
+                slug,
+                name: nameField,
+                docs: { ...docs, root: toPosix(path.relative(cwd, docsAbs)) },
+                hasDocsKey: !!raw.docs && typeof raw.docs === 'object',
+                ...(docsRootInferred ? { docsRootInferred } : {}),
+            };
+        }
+    }
+    throw new ProductConfigMissingError(startDir);
+}
+/** Versão do `package.json` do produto (pasta do config; senão a base). */
+export function readProductVersion(repo) {
+    for (const dir of [repo.configDir, repo.cwd]) {
+        try {
+            const v = JSON.parse(fsSync.readFileSync(path.join(dir, 'package.json'), 'utf8').replace(/^\uFEFF/, '')).version;
+            if (typeof v === 'string' && v.trim())
+                return v.trim();
+        }
+        catch {
+            /* próximo */
+        }
+    }
+    return undefined;
+}
+/**
+ * Garante a chave `docs` no config, acrescentando SÓ as subchaves que faltam
+ * (nunca muda valor existente, salvo as listadas em `override`). Devolve as
+ * subchaves acrescentadas/alteradas.
+ */
+export async function ensureDocsKey(repo, extra = {}, dryRun = false, 
+/** Subchaves de `extra` que valem mesmo se já existirem (pedido explícito do usuário). */
+override = []) {
+    const current = (repo.raw.docs && typeof repo.raw.docs === 'object' ? repo.raw.docs : {});
+    const wanted = {
+        protocolVersion: DEFAULT_DOCS_CONFIG.protocolVersion,
+        root: repo.docsRootInferred ?? DEFAULT_DOCS_CONFIG.root,
+        publish: DEFAULT_DOCS_CONFIG.publish,
+        publishOnDeploy: DEFAULT_DOCS_CONFIG.publishOnDeploy,
+        ...extra,
+    };
+    const added = [];
+    const next = { ...current };
+    for (const [k, v] of Object.entries(wanted)) {
+        if (!(k in current) || (override.includes(k) && current[k] !== v)) {
+            next[k] = v;
+            added.push(k);
+        }
+    }
+    if (added.length === 0)
+        return [];
+    if (!dryRun) {
+        const updated = { ...repo.raw, docs: next };
+        const original = await fs.readFile(repo.configPath, 'utf8');
+        const eol = original.includes('\r\n') ? '\r\n' : '\n';
+        const indentMatch = original.match(/^[ \t]+(?=")/m);
+        const indent = indentMatch ? indentMatch[0] : '  ';
+        // Preserva o estilo do arquivo: fim de linha, indentação e (ausência de) quebra final.
+        const finalEol = /\r?\n$/.test(original) ? eol : '';
+        const text = JSON.stringify(updated, null, indent).replace(/\n/g, eol) + finalEol;
+        const tmp = `${repo.configPath}.${process.pid}.tmp`;
+        await fs.writeFile(tmp, text, 'utf8');
+        await fs.rename(tmp, repo.configPath);
+        repo.raw = updated;
+        // `root` em memória continua relativo à base (já resolvido no load).
+        repo.docs = { ...normalizeDocsConfig(next), root: repo.docs.root };
+        repo.hasDocsKey = true;
+    }
+    return added;
+}
+/**
+ * O produto expõe `/api/v1`? `docs.api: true`, ou app móvel registrado
+ * (`.neetru/mobile.json` com apps), ou o config declara `mobile`/`integrations`.
+ */
+export function productExposesApi(repo) {
+    if (repo.docs.api)
+        return true;
+    const raw = repo.raw;
+    const truthy = (v) => v === true || (Array.isArray(v) && v.length > 0) || (!!v && typeof v === 'object' && Object.keys(v).length > 0);
+    if (truthy(raw.mobile) || truthy(raw.mobileApps) || truthy(raw.integrations) || truthy(raw.integracoes))
+        return true;
+    try {
+        const p = path.join(repo.configDir, '.neetru', 'mobile.json');
+        if (fsSync.existsSync(p)) {
+            const m = JSON.parse(fsSync.readFileSync(p, 'utf8'));
+            if (Array.isArray(m.apps) && m.apps.length > 0)
+                return true;
+        }
+    }
+    catch {
+        /* ignora */
+    }
+    return false;
+}
+//# sourceMappingURL=config.js.map

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

@@ -0,0 +1,17 @@
+/**
+ * Datas dos docs (AAAA-MM-DD) no FUSO DO NEGÓCIO, nunca em UTC.
+ *
+ * Bug da migração real (2026-10-03): `toISOString()` é UTC — depois das 21h
+ * BRT os docs criados, o nome do relatório `MIGRACAO_DOCS_<data>`, o
+ * `gerado_em` e a data do CHANGELOG saíam com o dia seguinte.
+ *
+ * Fuso: `NEETRU_TZ` (ex.: `America/Manaus`) quando definido; senão
+ * `America/Sao_Paulo` — explícito de propósito: o fuso "local" de um container
+ * de CI costuma ser UTC e reintroduziria o bug.
+ */
+export declare const DEFAULT_DOCS_TZ = "America/Sao_Paulo";
+export declare function docsTimeZone(): string;
+/** AAAA-MM-DD de `d` no fuso dos docs. */
+export declare function localIsoDate(d?: Date, timeZone?: string): string;
+/** Hoje (AAAA-MM-DD) no fuso dos docs. Usa `Date.now()` — o relógio é injetável em teste. */
+export declare function todayIso(): string;

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

@@ -0,0 +1,41 @@
+/**
+ * Datas dos docs (AAAA-MM-DD) no FUSO DO NEGÓCIO, nunca em UTC.
+ *
+ * Bug da migração real (2026-10-03): `toISOString()` é UTC — depois das 21h
+ * BRT os docs criados, o nome do relatório `MIGRACAO_DOCS_<data>`, o
+ * `gerado_em` e a data do CHANGELOG saíam com o dia seguinte.
+ *
+ * Fuso: `NEETRU_TZ` (ex.: `America/Manaus`) quando definido; senão
+ * `America/Sao_Paulo` — explícito de propósito: o fuso "local" de um container
+ * de CI costuma ser UTC e reintroduziria o bug.
+ */
+export const DEFAULT_DOCS_TZ = 'America/Sao_Paulo';
+export function docsTimeZone() {
+    const tz = process.env.NEETRU_TZ?.trim();
+    if (tz) {
+        try {
+            new Intl.DateTimeFormat('en-CA', { timeZone: tz });
+            return tz;
+        }
+        catch {
+            /* fuso inválido → padrão */
+        }
+    }
+    return DEFAULT_DOCS_TZ;
+}
+/** AAAA-MM-DD de `d` no fuso dos docs. */
+export function localIsoDate(d = new Date(), timeZone = docsTimeZone()) {
+    const parts = new Intl.DateTimeFormat('en-CA', {
+        timeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).formatToParts(d);
+    const get = (t) => parts.find((p) => p.type === t)?.value ?? '';
+    return `${get('year')}-${get('month')}-${get('day')}`;
+}
+/** Hoje (AAAA-MM-DD) no fuso dos docs. Usa `Date.now()` — o relógio é injetável em teste. */
+export function todayIso() {
+    return localIsoDate(new Date());
+}
+//# sourceMappingURL=dates.js.map

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

@@ -0,0 +1,43 @@
+/**
+ * Frontmatter YAML dos docs — parser e serializador SEM dependência.
+ *
+ * O CLI publicado não carrega `js-yaml`/`gray-matter`. Este parser cobre o
+ * subconjunto que o protocolo usa (e o que aparece nos repos de produto):
+ *   - `chave: valor` (string sem aspas, "aspas duplas" com escapes, 'aspas simples')
+ *   - inteiros, `true`/`false`, `null`/`~`
+ *   - lista em linha `[a, "b c"]` e lista em bloco (`chave:` + linhas `  - item`)
+ *   - bloco literal/dobrado (`chave: |` / `chave: >`)
+ *   - mapa aninhado de 1 nível (`chave:` + linhas `  sub: valor`) — fica como objeto
+ *   - comentários `#` em linha própria
+ *
+ * Erros que um parser YAML de verdade recusaria viram `error` (o validador
+ * reporta FM001): bloco sem fechamento, linha que não é `chave: valor`,
+ * indentação com TAB, chave duplicada, aspas sem fechamento.
+ *
+ * Datas (`2026-10-03`) ficam como STRING — o validador confere o formato.
+ */
+export type FmValue = string | number | boolean | null | FmValue[] | {
+    [k: string]: FmValue;
+};
+export type FmData = Record<string, FmValue>;
+export interface ParsedDoc {
+    /** `true` quando o arquivo começa com `---` (com ou sem BOM). */
+    hasFrontmatter: boolean;
+    data: FmData;
+    /** Corpo depois do bloco de frontmatter (ou o arquivo inteiro, sem frontmatter). */
+    body: string;
+    /** Linha (1-based) onde o corpo começa no arquivo original. */
+    bodyStartLine: number;
+    /** Mensagem do erro de YAML (FM001), se houver. */
+    error?: string;
+    /** O arquivo começava com BOM UTF-8. */
+    bom: boolean;
+    /** Fim de linha dominante do arquivo. */
+    eol: '\n' | '\r\n';
+}
+/** Separa e interpreta o frontmatter de um markdown. Nunca lança. */
+export declare function parseDoc(raw: string): ParsedDoc;
+/** Ordem canônica das chaves (§6.1 do protocolo da wiki + `product`). */
+export declare const FRONTMATTER_KEY_ORDER: string[];
+/** Gera o bloco `---\n...\n---` (sem quebra final). Chaves conhecidas em ordem canônica, o resto depois. */
+export declare function serializeFrontmatter(data: FmData, eol?: '\n' | '\r\n'): string;

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

@@ -0,0 +1,302 @@
+/**
+ * Frontmatter YAML dos docs — parser e serializador SEM dependência.
+ *
+ * O CLI publicado não carrega `js-yaml`/`gray-matter`. Este parser cobre o
+ * subconjunto que o protocolo usa (e o que aparece nos repos de produto):
+ *   - `chave: valor` (string sem aspas, "aspas duplas" com escapes, 'aspas simples')
+ *   - inteiros, `true`/`false`, `null`/`~`
+ *   - lista em linha `[a, "b c"]` e lista em bloco (`chave:` + linhas `  - item`)
+ *   - bloco literal/dobrado (`chave: |` / `chave: >`)
+ *   - mapa aninhado de 1 nível (`chave:` + linhas `  sub: valor`) — fica como objeto
+ *   - comentários `#` em linha própria
+ *
+ * Erros que um parser YAML de verdade recusaria viram `error` (o validador
+ * reporta FM001): bloco sem fechamento, linha que não é `chave: valor`,
+ * indentação com TAB, chave duplicada, aspas sem fechamento.
+ *
+ * Datas (`2026-10-03`) ficam como STRING — o validador confere o formato.
+ */
+const BOM = '';
+function detectEol(raw) {
+    const crlf = (raw.match(/\r\n/g) ?? []).length;
+    const lf = (raw.match(/\n/g) ?? []).length - crlf;
+    return crlf > lf ? '\r\n' : '\n';
+}
+function parseScalar(rawVal) {
+    const v = rawVal.trim();
+    if (v === '')
+        return { value: null };
+    if (v.startsWith('"')) {
+        // acha o fechamento respeitando escapes
+        let out = '';
+        let i = 1;
+        let closed = false;
+        while (i < v.length) {
+            const c = v[i];
+            if (c === '\\' && i + 1 < v.length) {
+                const n = v[i + 1];
+                out += n === 'n' ? '\n' : n === 't' ? '\t' : n;
+                i += 2;
+                continue;
+            }
+            if (c === '"') {
+                closed = true;
+                i++;
+                break;
+            }
+            out += c;
+            i++;
+        }
+        if (!closed)
+            return { value: v, error: 'aspas duplas sem fechamento' };
+        const rest = v.slice(i).trim();
+        if (rest && !rest.startsWith('#'))
+            return { value: out, error: `conteúdo depois das aspas: "${rest}"` };
+        return { value: out };
+    }
+    if (v.startsWith("'")) {
+        let out = '';
+        let i = 1;
+        let closed = false;
+        while (i < v.length) {
+            if (v[i] === "'") {
+                if (v[i + 1] === "'") {
+                    out += "'";
+                    i += 2;
+                    continue;
+                }
+                closed = true;
+                i++;
+                break;
+            }
+            out += v[i];
+            i++;
+        }
+        if (!closed)
+            return { value: v, error: 'aspas simples sem fechamento' };
+        const rest = v.slice(i).trim();
+        if (rest && !rest.startsWith('#'))
+            return { value: out, error: `conteúdo depois das aspas: "${rest}"` };
+        return { value: out };
+    }
+    if (v.startsWith('[')) {
+        if (!v.endsWith(']'))
+            return { value: v, error: 'lista em linha sem "]"' };
+        const inner = v.slice(1, -1).trim();
+        if (inner === '')
+            return { value: [] };
+        const items = [];
+        let cur = '';
+        let quote = null;
+        for (const ch of inner) {
+            if (quote) {
+                cur += ch;
+                if (ch === quote)
+                    quote = null;
+                continue;
+            }
+            if (ch === '"' || ch === "'") {
+                quote = ch;
+                cur += ch;
+                continue;
+            }
+            if (ch === ',') {
+                const r = parseScalar(cur);
+                if (r.error)
+                    return { value: v, error: r.error };
+                items.push(r.value);
+                cur = '';
+                continue;
+            }
+            cur += ch;
+        }
+        if (quote)
+            return { value: v, error: 'aspas sem fechamento na lista' };
+        const r = parseScalar(cur);
+        if (r.error)
+            return { value: v, error: r.error };
+        items.push(r.value);
+        return { value: items };
+    }
+    // comentário no fim da linha (` #`) — corta
+    const hash = v.search(/\s#/);
+    const plain = hash >= 0 ? v.slice(0, hash).trim() : v;
+    if (plain === 'true')
+        return { value: true };
+    if (plain === 'false')
+        return { value: false };
+    if (plain === 'null' || plain === '~')
+        return { value: null };
+    if (/^-?\d+$/.test(plain))
+        return { value: Number.parseInt(plain, 10) };
+    return { value: plain };
+}
+/** Separa e interpreta o frontmatter de um markdown. Nunca lança. */
+export function parseDoc(raw) {
+    const eol = detectEol(raw);
+    const bom = raw.startsWith(BOM);
+    const text = bom ? raw.slice(1) : raw;
+    const lines = text.split(/\r?\n/);
+    const base = { hasFrontmatter: false, data: {}, body: text, bodyStartLine: 1, bom, eol };
+    if (lines[0]?.trim() !== '---')
+        return base;
+    let end = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === '---' || lines[i].trim() === '...') {
+            end = i;
+            break;
+        }
+    }
+    if (end < 0) {
+        return { ...base, hasFrontmatter: true, error: 'bloco de frontmatter sem a linha "---" de fechamento' };
+    }
+    const fmLines = lines.slice(1, end);
+    const body = lines.slice(end + 1).join(eol);
+    const out = { ...base, hasFrontmatter: true, body, bodyStartLine: end + 2 };
+    const data = {};
+    let i = 0;
+    const fail = (lineIdx, msg) => ({
+        ...out,
+        data,
+        error: `linha ${lineIdx + 2} do frontmatter: ${msg}`,
+    });
+    while (i < fmLines.length) {
+        const line = fmLines[i];
+        if (line.trim() === '' || line.trim().startsWith('#')) {
+            i++;
+            continue;
+        }
+        if (/^\t/.test(line))
+            return fail(i, 'indentação com TAB não é YAML válido');
+        if (/^\s/.test(line))
+            return fail(i, `linha indentada fora de uma lista ou bloco: "${line.trim()}"`);
+        const kv = line.match(/^([A-Za-z_$][\w$.-]*)\s*:(?:\s+(.*)|\s*)$/);
+        if (!kv)
+            return fail(i, `esperado "chave: valor", veio "${line.trim()}"`);
+        const key = kv[1];
+        const rest = (kv[2] ?? '').trim();
+        if (Object.prototype.hasOwnProperty.call(data, key))
+            return fail(i, `chave "${key}" repetida`);
+        if (rest === '|' || rest === '>' || rest === '|-' || rest === '>-') {
+            const parts = [];
+            i++;
+            while (i < fmLines.length && (/^\s+/.test(fmLines[i]) || fmLines[i].trim() === '')) {
+                if (/^\t/.test(fmLines[i]))
+                    return fail(i, 'indentação com TAB não é YAML válido');
+                parts.push(fmLines[i].trim());
+                i++;
+            }
+            data[key] = rest.startsWith('|') ? parts.join('\n').trim() : parts.filter(Boolean).join(' ').trim();
+            continue;
+        }
+        if (rest === '' || rest.startsWith('#')) {
+            // lista em bloco, mapa aninhado ou vazio
+            const items = [];
+            const map = {};
+            let kind = null;
+            i++;
+            while (i < fmLines.length && (/^\s+/.test(fmLines[i]) || fmLines[i].trim() === '' || /^-\s/.test(fmLines[i]))) {
+                const l = fmLines[i];
+                if (l.trim() === '' || l.trim().startsWith('#')) {
+                    i++;
+                    continue;
+                }
+                if (/^\t/.test(l))
+                    return fail(i, 'indentação com TAB não é YAML válido');
+                const t = l.trim();
+                if (t.startsWith('- ') || t === '-') {
+                    if (kind === 'mapa')
+                        return fail(i, 'mistura de lista e mapa');
+                    kind = 'lista';
+                    const r = parseScalar(t.slice(1));
+                    if (r.error)
+                        return fail(i, r.error);
+                    items.push(r.value);
+                }
+                else {
+                    if (kind === 'lista')
+                        return fail(i, 'mistura de lista e mapa');
+                    kind = 'mapa';
+                    const sub = t.match(/^([A-Za-z_$][\w$.-]*)\s*:(?:\s+(.*)|\s*)$/);
+                    if (!sub)
+                        return fail(i, `esperado "chave: valor" dentro de "${key}"`);
+                    const r = parseScalar(sub[2] ?? '');
+                    if (r.error)
+                        return fail(i, r.error);
+                    map[sub[1]] = r.value;
+                }
+                i++;
+            }
+            data[key] = kind === 'lista' ? items : kind === 'mapa' ? map : null;
+            continue;
+        }
+        const r = parseScalar(rest);
+        if (r.error)
+            return fail(i, r.error);
+        data[key] = r.value;
+        i++;
+    }
+    return { ...out, data };
+}
+// ─── serialização ─────────────────────────────────────────────────────────
+/** Ordem canônica das chaves (§6.1 do protocolo da wiki + `product`). */
+export const FRONTMATTER_KEY_ORDER = [
+    'title', 'description', 'product', 'category', 'subcategory', 'type', 'status',
+    'date', 'updated', 'owner', 'audience', 'adr', 'order', 'superseded_by', 'supersedes',
+    'archived_at', 'archived_from', 'archive_reason', 'status_evidence', 'status_checked_at',
+    'status_note', 'related', 'tags', 'icon', 'command',
+];
+/** Chaves cujo valor sempre vai entre aspas duplas (texto livre). */
+const ALWAYS_QUOTE = new Set(['title', 'description', 'archive_reason', 'status_note', 'status_evidence']);
+function needsQuote(s) {
+    if (s === '')
+        return true;
+    // inclui os booleanos do YAML 1.1 (yes/no/on/off) — parsers antigos os leem como bool
+    if (/^(true|false|yes|no|on|off|null|~|-?\d+(\.\d+)?)$/i.test(s))
+        return true;
+    if (/^[\s\-?:,[\]{}#&*!|>'"%@`]/.test(s))
+        return true;
+    if (/:\s|\s#|[\r\n\t]/.test(s) || s.endsWith(':') || s.endsWith(' '))
+        return true;
+    return false;
+}
+function quote(s) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`;
+}
+function serializeScalar(key, v) {
+    if (v === null)
+        return '';
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    if (Array.isArray(v))
+        return `[${v.map((x) => serializeScalar('', x)).join(', ')}]`;
+    if (typeof v === 'object')
+        return JSON.stringify(v);
+    if (ALWAYS_QUOTE.has(key) || needsQuote(v))
+        return quote(v);
+    return v;
+}
+/** Gera o bloco `---\n...\n---` (sem quebra final). Chaves conhecidas em ordem canônica, o resto depois. */
+export function serializeFrontmatter(data, eol = '\n') {
+    const keys = Object.keys(data);
+    const ordered = [
+        ...FRONTMATTER_KEY_ORDER.filter((k) => keys.includes(k)),
+        ...keys.filter((k) => !FRONTMATTER_KEY_ORDER.includes(k)),
+    ];
+    const lines = ['---'];
+    for (const k of ordered) {
+        const v = data[k];
+        if (v === undefined)
+            continue;
+        if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+            lines.push(`${k}:`);
+            for (const [sk, sv] of Object.entries(v))
+                lines.push(`  ${sk}: ${serializeScalar(sk, sv)}`.trimEnd());
+            continue;
+        }
+        lines.push(`${k}: ${serializeScalar(k, v)}`.trimEnd());
+    }
+    lines.push('---');
+    return lines.join(eol);
+}
+//# sourceMappingURL=frontmatter.js.map

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

@@ -0,0 +1,16 @@
+export declare function git(cwd: string, args: string[]): string | null;
+/** Ref base para comparar ("branch principal"): origin/main, main, origin/master, master. */
+export declare function resolveBaseRef(cwd: string): string | null;
+/**
+ * Arquivos alterados contra a branch principal (commits da branch + mudanças
+ * não commitadas + arquivos novos não rastreados). Caminhos relativos à raiz
+ * do repo, com `/`. `null` = não deu para descobrir (sem git, sem base).
+ */
+export declare function changedFiles(cwd: string): {
+    files: string[];
+    base: string;
+} | null;
+/** Data (AAAA-MM-DD) do commit que CRIOU o arquivo, seguindo renomeações. */
+export declare function firstCommitDate(cwd: string, relPath: string): string | null;
+/** Data (AAAA-MM-DD) do último commit que tocou o arquivo. */
+export declare function lastCommitDate(cwd: string, relPath: string): string | null;