@memoring/cli 0.12.1 → 0.15.0

package/dist/commands/materialReferences.js

@@ -0,0 +1,359 @@
+import { readFileSync } from 'node:fs';
+import { apiFetch, ApiError } from '../api.js';
+import { dim, fail, green, printJson, printTable, stringFlag } from './shared.js';
+// ---------------------------------------------------------------------------
+// Limites e tipos — única fronteira de validação das referências de material
+// (stage create e reference update usam OS MESMOS validadores).
+// ---------------------------------------------------------------------------
+/** Limites espelhando a validação do backend (V234/V243). */
+export const MATERIAL_DRIVE_FILE_ID_MAX = 255;
+export const MATERIAL_EXCERPT_MAX = 500;
+export const MATERIAL_QUOTE_MAX = 1000;
+export const MATERIAL_CONTEXT_MAX = 500;
+const REGION_EPSILON = 1e-9;
+/**
+ * Geometria da região: objeto {x,y,w,h} com números FINITOS, w/h > 0 e retângulo
+ * contido no unit square (0 <= x, 0 <= y, x+w <= 1, y+h <= 1). Um overshoot de até
+ * REGION_EPSILON é tolerado como ruído de float, mas NUNCA vai no fio: x/y são
+ * elevados a 0 e w/h encolhidos até a borda (1-x/1-y) — o resultado sempre satisfaz
+ * o CHECK estrito do backend. Overshoot além da tolerância (ou sem espaço p/ w/h > 0)
+ * continua erro. Usado pelo stage (materialReferences.region) e pelo reference update.
+ */
+export function validateRegion(raw, where) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        fail(`${where}: region deve ser um objeto { x, y, w, h } (veio ${raw === null ? 'null' : Array.isArray(raw) ? 'array' : typeof raw}).`);
+    }
+    const r = raw;
+    for (const key of ['x', 'y', 'w', 'h']) {
+        const value = r[key];
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            fail(`${where}: region.${key} deve ser um número finito (veio ${JSON.stringify(value)}).`);
+        }
+    }
+    const region = r;
+    if (region.w <= 0 || region.h <= 0) {
+        fail(`${where}: region exige w e h > 0 (veio w=${region.w}, h=${region.h}).`);
+    }
+    if (region.x < -REGION_EPSILON ||
+        region.y < -REGION_EPSILON ||
+        region.x + region.w > 1 + REGION_EPSILON ||
+        region.y + region.h > 1 + REGION_EPSILON) {
+        fail(`${where}: region deve estar contida no unit square (0..1) — veio ` +
+            `{ x: ${region.x}, y: ${region.y}, w: ${region.w}, h: ${region.h} }.`);
+    }
+    // Clamp do overshoot tolerado: o wire nunca carrega valor fora do quadrado nem
+    // coordenada negativa (o CHECK do backend é estrito). x > 1 dentro da tolerância
+    // deixaria w/h sem espaço — degenera a região, então é rejeitado em vez de inventar
+    // coordenada.
+    const x = Math.max(0, region.x);
+    const y = Math.max(0, region.y);
+    const w = Math.min(region.w, 1 - x);
+    const h = Math.min(region.h, 1 - y);
+    if (w <= 0 || h <= 0) {
+        fail(`${where}: region deve estar contida no unit square (0..1) — veio ` +
+            `{ x: ${region.x}, y: ${region.y}, w: ${region.w}, h: ${region.h} }.`);
+    }
+    return { x, y, w, h };
+}
+/** Texto opcional do stage: string trim não-vazia até `max`; vazio normaliza para ausente. */
+function validateStageText(raw, field, max, where) {
+    if (typeof raw !== 'string') {
+        fail(`${where}: ${field} deve ser uma string (veio ${typeof raw}).`);
+    }
+    const trimmed = raw.trim();
+    if (trimmed.length > max) {
+        fail(`${where}: ${field} tem ${trimmed.length} chars (máximo ${max}).`);
+    }
+    return trimmed === '' ? undefined : trimmed;
+}
+/**
+ * Valida e normaliza as referências de material do lote ANTES de qualquer chamada de API:
+ * cada entrada precisa ser objeto com driveFileId (string trim não vazia, até 255),
+ * page (inteiro >= 1, 1-based), excerpt/quote/contextBefore/contextAfter opcionais
+ * (trim nos tetos; vazio vira ausente) e region opcional (geometria validada por
+ * validateRegion). `undefined`/`null`/array vazio normalizam para ausente (o campo é
+ * omitido no POST, mantendo o payload antigo dos lotes sem referências).
+ */
+export function validateMaterialReferences(raw, where) {
+    if (raw === undefined || raw === null) {
+        return undefined;
+    }
+    if (!Array.isArray(raw)) {
+        fail(`${where}: materialReferences deve ser um array (veio ${typeof raw}).`);
+    }
+    if (raw.length === 0) {
+        return undefined;
+    }
+    return raw.map((entry, index) => {
+        const ref = `${where}: materialReferences[${index + 1}]`;
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            fail(`${ref} deve ser um objeto { driveFileId, page, excerpt?, quote?, contextBefore?, contextAfter?, region? }.`);
+        }
+        const r = entry;
+        if (typeof r.driveFileId !== 'string' || r.driveFileId.trim() === '') {
+            fail(`${ref}: driveFileId é obrigatório (string não vazia — veja \`memoring scratch list --json\`).`);
+        }
+        const driveFileId = r.driveFileId.trim();
+        if (driveFileId.length > MATERIAL_DRIVE_FILE_ID_MAX) {
+            fail(`${ref}: driveFileId tem ${driveFileId.length} chars (máximo ${MATERIAL_DRIVE_FILE_ID_MAX}).`);
+        }
+        if (typeof r.page !== 'number' || !Number.isInteger(r.page) || r.page < 1) {
+            fail(`${ref}: page deve ser um inteiro >= 1 (página visível, 1-based — veio ${JSON.stringify(r.page)}).`);
+        }
+        let excerpt;
+        if (r.excerpt !== undefined && r.excerpt !== null) {
+            excerpt = validateStageText(r.excerpt, 'excerpt', MATERIAL_EXCERPT_MAX, ref);
+        }
+        let quote;
+        if (r.quote !== undefined && r.quote !== null) {
+            quote = validateStageText(r.quote, 'quote', MATERIAL_QUOTE_MAX, ref);
+        }
+        let contextBefore;
+        if (r.contextBefore !== undefined && r.contextBefore !== null) {
+            contextBefore = validateStageText(r.contextBefore, 'contextBefore', MATERIAL_CONTEXT_MAX, ref);
+        }
+        let contextAfter;
+        if (r.contextAfter !== undefined && r.contextAfter !== null) {
+            contextAfter = validateStageText(r.contextAfter, 'contextAfter', MATERIAL_CONTEXT_MAX, ref);
+        }
+        let region;
+        if (r.region !== undefined && r.region !== null) {
+            region = validateRegion(r.region, ref);
+        }
+        return {
+            driveFileId,
+            page: r.page,
+            ...(excerpt !== undefined ? { excerpt } : {}),
+            ...(quote !== undefined ? { quote } : {}),
+            ...(contextBefore !== undefined ? { contextBefore } : {}),
+            ...(contextAfter !== undefined ? { contextAfter } : {}),
+            ...(region !== undefined ? { region } : {}),
+        };
+    });
+}
+/**
+ * Conversão para o fio (POST /notes/review-inbox): page 1-based vira `pageIndex` 0-based
+ * (page NUNCA vaza) e os demais campos são repassados. Campos ausentes são omitidos —
+ * lotes antigos (só driveFileId/page/excerpt) saem byte a byte como antes.
+ */
+export function toWireMaterialReference(ref) {
+    return {
+        driveFileId: ref.driveFileId,
+        pageIndex: ref.page - 1,
+        ...(ref.excerpt !== undefined ? { excerpt: ref.excerpt } : {}),
+        ...(ref.quote !== undefined ? { quote: ref.quote } : {}),
+        ...(ref.contextBefore !== undefined ? { contextBefore: ref.contextBefore } : {}),
+        ...(ref.contextAfter !== undefined ? { contextAfter: ref.contextAfter } : {}),
+        ...(ref.region !== undefined ? { region: ref.region } : {}),
+    };
+}
+/**
+ * Contrato das referências de material no idioma do AGENTE (page 1-based), como o
+ * `stage schema` o expõe. No POST cada referência sai como
+ * { driveFileId, pageIndex: page - 1, excerpt?, quote?, contextBefore?, contextAfter?, region? }.
+ */
+export const MATERIAL_REFERENCE_CONTRACT = {
+    driveFileId: `string (obrigatório) — id do arquivo no Drive; descubra com \`memoring scratch list --json\` (trim, não vazio, até ${MATERIAL_DRIVE_FILE_ID_MAX} chars)`,
+    page: 'int 1-based (obrigatório) — página VISÍVEL do PDF (a posição 1-based no documento, como no `scratch extract --pages`); o POST converte para pageIndex 0-based',
+    excerpt: `string? — dica curta do trecho que originou o item (trim, até ${MATERIAL_EXCERPT_MAX} chars; vazio = omitido). É SÓ um rótulo humano: NÃO gera destaque no PDF`,
+    quote: `string? — trecho LITERAL do material que originou o item (trim, até ${MATERIAL_QUOTE_MAX} chars; vazio = omitido). RECOMENDADO para PDF com texto: é o que o app localiza e destaca na página`,
+    contextBefore: `string? — texto imediatamente ANTES do quote no material (trim, até ${MATERIAL_CONTEXT_MAX} chars; vazio = omitido) — desempata ocorrências repetidas do quote`,
+    contextAfter: `string? — texto imediatamente DEPOIS do quote no material (trim, até ${MATERIAL_CONTEXT_MAX} chars; vazio = omitido) — desempata ocorrências repetidas do quote`,
+    region: 'objeto? { x, y, w, h } — região visual da página, coordenadas normalizadas 0..1 com origem no topo-esquerdo (x,y) e tamanho (w,h); todos números FINITOS, w/h > 0 e retângulo contido no quadrado 0..1 (x+w <= 1, y+h <= 1). Para PDF ESCANEADO/sem texto: selecione a região do recorte em vez de quote. Alternativa ao quote — um ou outro (ou nenhum, só a página)',
+};
+// ---------------------------------------------------------------------------
+// memoring reference list/update — manutenção das referências de um card.
+// ---------------------------------------------------------------------------
+const UPDATE_FIELDS = ['excerpt', 'quote', 'contextBefore', 'contextAfter', 'region'];
+function parseId(arg, what, usage) {
+    const id = Number(arg);
+    if (!arg || !Number.isInteger(id) || id <= 0) {
+        fail(`informe o ${what} numérico: ${usage} (veja os ids com \`memoring reference list <noteId> --json\`).`);
+    }
+    return id;
+}
+async function fetchReferences(noteId) {
+    let body;
+    try {
+        body = await apiFetch(`/notes/${noteId}/material-references`);
+    }
+    catch (e) {
+        if (e instanceof ApiError && e.status === 404) {
+            fail(`card #${noteId} não encontrado (ou de outro usuário) — confira o id com \`memoring inbox list\` ou \`memoring deck list\`.`);
+        }
+        throw e;
+    }
+    const references = body?.references;
+    if (!Array.isArray(references)) {
+        fail(`resposta inesperada do servidor ao listar as referências do card #${noteId} (falta o array "references").`);
+    }
+    return references;
+}
+function truncate(value, max) {
+    return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
+}
+/** Página de exibição (1-based, o idioma do agente) — '—' quando o servidor não a tem. */
+function pageLabel(ref) {
+    return typeof ref.pageIndex === 'number' ? ref.pageIndex + 1 : '—';
+}
+async function listReferences(parsed, noteId) {
+    const references = await fetchReferences(noteId);
+    if (parsed.flags.json) {
+        printJson(references);
+        return;
+    }
+    if (references.length === 0) {
+        process.stdout.write(`Card #${noteId} não tem referências de material.\n`);
+        return;
+    }
+    printTable(references.map((r) => ({
+        id: `#${r.id}`,
+        page: pageLabel(r),
+        file: truncate(r.driveFileId ?? '', 28),
+        highlight: r.region ? 'região' : r.quote ? 'quote' : '—',
+        summary: truncate(r.excerpt ?? r.quote ?? '—', 48),
+    })), [
+        { key: 'id', label: 'ID' },
+        { key: 'page', label: 'PÁGINA' },
+        { key: 'file', label: 'ARQUIVO' },
+        { key: 'highlight', label: 'DESTAQUE' },
+        { key: 'summary', label: 'RESUMO' },
+    ]);
+    process.stdout.write(`\n${references.length} referência(s) no card #${noteId} — página exibida 1-based. ` +
+        'Corrija excerpt/quote/contextos/região com `memoring reference update ' +
+        `<noteId> <referenceId> --file parcial.json\` (region: null limpa a região).\n`);
+}
+/**
+ * Merge de um campo de texto do patch com a referência atual: chave AUSENTE mantém o
+ * valor atual; null (ou string que trima para vazio) LIMPA; string válida valida
+ * (trim + teto) e substitui.
+ */
+function mergeTextField(current, raw, field, max, where) {
+    if (raw === undefined) {
+        return current ?? null;
+    }
+    if (raw === null) {
+        return null;
+    }
+    if (typeof raw !== 'string') {
+        fail(`${where}: ${field} deve ser uma string ou null (veio ${typeof raw}).`);
+    }
+    const trimmed = raw.trim();
+    if (trimmed.length > max) {
+        fail(`${where}: ${field} tem ${trimmed.length} chars (máximo ${max}).`);
+    }
+    return trimmed === '' ? null : trimmed;
+}
+/** Merge da região: chave AUSENTE mantém; null LIMPA; objeto valida pela geometria comum. */
+function mergeRegion(current, raw, where) {
+    if (raw === undefined) {
+        return current ?? null;
+    }
+    if (raw === null) {
+        return null;
+    }
+    return validateRegion(raw, where);
+}
+function readPatchFile(parsed) {
+    const file = stringFlag(parsed.flags, 'file');
+    if (!file) {
+        fail('informe o patch: memoring reference update <noteId> <referenceId> --file parcial.json ' +
+            '(excerpt/quote/contextBefore/contextAfter/region — campos ausentes são mantidos; region: null limpa).');
+    }
+    let patch;
+    try {
+        patch = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        fail(`JSON inválido em --file: ${e.message}`);
+    }
+    if (typeof patch !== 'object' || patch === null || Array.isArray(patch)) {
+        fail(`--file deve ser um objeto JSON parcial com os campos ${UPDATE_FIELDS.map((f) => `"${f}"`).join(', ')} (veio ${Array.isArray(patch) ? 'array' : typeof patch}).`);
+    }
+    const record = patch;
+    const unknown = Object.keys(record).filter((k) => !UPDATE_FIELDS.includes(k));
+    if (unknown.length > 0) {
+        fail(`campo(s) desconhecido(s) no patch: ${unknown.map((k) => `"${k}"`).join(', ')} — o update só aceita ` +
+            `${UPDATE_FIELDS.map((f) => `"${f}"`).join(', ')} (nota, driveFileId e página NÃO são alterados por aqui).`);
+    }
+    return record;
+}
+async function updateReference(parsed, noteId, referenceId) {
+    const patch = readPatchFile(parsed);
+    const references = await fetchReferences(noteId);
+    const current = references.find((r) => r.id === referenceId);
+    if (!current) {
+        fail(`referência #${referenceId} não encontrada no card #${noteId} — veja os ids com \`memoring reference list ${noteId} --json\`.`);
+    }
+    const where = `referência #${referenceId}`;
+    // PUT full replace DESSAS METADADAS: o body sempre leva os 5 campos com o resultado
+    // do merge (ausente = manter o atual; null = limpar). Nota, driveFileId e página
+    // não entram no body — o servidor não os troca por esse endpoint.
+    const body = {
+        excerpt: mergeTextField(current.excerpt, patch.excerpt, 'excerpt', MATERIAL_EXCERPT_MAX, where),
+        quote: mergeTextField(current.quote, patch.quote, 'quote', MATERIAL_QUOTE_MAX, where),
+        contextBefore: mergeTextField(current.contextBefore, patch.contextBefore, 'contextBefore', MATERIAL_CONTEXT_MAX, where),
+        contextAfter: mergeTextField(current.contextAfter, patch.contextAfter, 'contextAfter', MATERIAL_CONTEXT_MAX, where),
+        region: mergeRegion(current.region, patch.region, where),
+    };
+    let updated;
+    try {
+        updated = (await apiFetch(`/notes/${noteId}/material-references/${referenceId}`, {
+            method: 'PUT',
+            body,
+        }));
+    }
+    catch (e) {
+        if (e instanceof ApiError) {
+            if (e.status === 404) {
+                fail(`referência #${referenceId} não encontrada no card #${noteId} (ou de outro usuário) — confira com \`memoring reference list ${noteId} --json\`.`);
+            }
+            fail(`o servidor rejeitou a atualização (${e.status}): ${e.body}`);
+        }
+        throw e;
+    }
+    const view = updated ?? { ...current, ...body };
+    if (parsed.flags.json) {
+        printJson(view);
+        return;
+    }
+    const showText = (v) => (v ? `"${truncate(v, 60)}"` : '—');
+    process.stdout.write(green(`Referência #${referenceId} do card #${noteId} atualizada:\n`));
+    process.stdout.write(`  página        ${pageLabel(view)} (inalterada — não se troca por aqui)\n`);
+    process.stdout.write(`  arquivo       ${view.driveFileId ?? '—'} (inalterado)\n`);
+    process.stdout.write(`  excerpt       ${showText(view.excerpt)}\n`);
+    process.stdout.write(`  quote         ${showText(view.quote)}\n`);
+    process.stdout.write(`  contextBefore ${showText(view.contextBefore)}\n`);
+    process.stdout.write(`  contextAfter  ${showText(view.contextAfter)}\n`);
+    process.stdout.write(`  region        ${view.region ? `{ x: ${view.region.x}, y: ${view.region.y}, w: ${view.region.w}, h: ${view.region.h} }` : '—'}\n`);
+    process.stdout.write(dim('Sem quote nem região o app abre a página sem destaque — excerpt é só uma dica curta.\n'));
+}
+export async function referenceCommand(parsed) {
+    const [sub, noteIdArg, referenceIdArg] = parsed._;
+    switch (sub) {
+        case 'list': {
+            const noteId = parseId(noteIdArg, 'id do card', 'memoring reference list <noteId>');
+            await listReferences(parsed, noteId);
+            return;
+        }
+        case 'update': {
+            const noteId = parseId(noteIdArg, 'id do card', 'memoring reference update <noteId> <referenceId> --file parcial.json');
+            const referenceId = parseId(referenceIdArg, 'id da referência', 'memoring reference update <noteId> <referenceId> --file parcial.json');
+            await updateReference(parsed, noteId, referenceId);
+            return;
+        }
+        default:
+            process.stdout.write('Uso: memoring reference <list|update> [--json]\n' +
+                '  list <noteId>                    referências de material de um card (fontes de estudo)\n' +
+                '                                   — GET /notes/{noteId}/material-references; a página sai\n' +
+                '                                     1-based e o DESTAQUE mostra se há quote ou região\n' +
+                '  update <noteId> <referenceId>    corrige excerpt/quote/contextBefore/contextAfter/region\n' +
+                '           --file parcial.json      (merge: campo ausente mantém o atual; null ou string\n' +
+                '                                     vazia LIMPA; region valida x,y,w,h em 0..1, w/h > 0).\n' +
+                '                                     Não altera nota, arquivo nem página. --json devolve a\n' +
+                '                                     referência atualizada\n');
+            if (sub) {
+                process.exitCode = 1;
+            }
+    }
+}

package/dist/commands/plan-analyze.js

@@ -0,0 +1,256 @@
+import { openAsBlob, statSync, writeFileSync } from 'node:fs';
+import { basename, extname, resolve } from 'node:path';
+import { apiFetch, apiFetchMultipart } from '../api.js';
+import { createDraftHandoff } from './planDrafts.js';
+import { fail, green, printJson, stringFlag, yellow } from './shared.js';
+import { normalized, object, readJson, } from './plan-shared.js';
+const MAX_ANALYSIS_FILES = 10;
+const MAX_PDF_BYTES = 50 * 1024 * 1024;
+const ANALYSIS_POLL_INTERVAL_MS = 1_000;
+const ANALYSIS_TIMEOUT_MS = 10 * 60 * 1_000;
+const MATURITIES = ['BEGINNER', 'INTERMEDIATE', 'ADVANCED'];
+export const ERROR_REASONS = ['UNKNOWN', 'FORGETTING', 'CONCEPTUAL_CONFUSION', 'INATTENTION', 'INTERPRETATION', 'TIME_SHORTAGE'];
+export const PLAN_SCHEMA = {
+    version: 1,
+    description: 'Contrato editável de memoring plan analyze/create. A análise usa IA somente no backend; revise o rascunho antes de criar.',
+    maturity: {
+        BEGINNER: 'Iniciante',
+        INTERMEDIATE: 'Intermediário',
+        ADVANCED: 'Avançado',
+    },
+    errorReasons: ERROR_REASONS,
+    plan: {
+        name: 'Planejamento para o concurso',
+        objective: 'Objetivo revisável do planejamento',
+        weeklyMinutes: 600,
+        activeSubjectLimit: 4,
+        programs: [
+            {
+                subjectName: 'Direito Constitucional',
+                maturity: 'BEGINNER',
+                relevance: 3,
+                deckId: null,
+                materials: [
+                    {
+                        name: 'constitucional.pdf',
+                        pageCount: 120,
+                        charCount: 240000,
+                        confidence: 0.85,
+                        warnings: [],
+                    },
+                ],
+                topics: [
+                    {
+                        title: 'Princípios fundamentais',
+                        materialIndex: 0,
+                        prerequisiteTopicIndex: null,
+                        sourceName: 'constitucional.pdf',
+                        sourceRef: null,
+                        tecNotebookId: null,
+                        pageFrom: 1,
+                        pageTo: 12,
+                        charCount: 24000,
+                        estimatedMinutes: 50,
+                    },
+                ],
+            },
+        ],
+    },
+    exam: {
+        planId: 123,
+        name: 'Simulado 1',
+        examDate: new Date().toISOString().slice(0, 10),
+        totalQuestions: 40,
+        correctAnswers: 28,
+        subjectResults: [{ subjectName: 'Direito Constitucional', totalQuestions: 20, correctAnswers: 15 }],
+    },
+    notes: [
+        'maturity é obrigatória em toda disciplina; os rótulos Iniciante, Intermediário e Avançado também são aceitos no arquivo.',
+        'materialIndex e prerequisiteTopicIndex são índices 0-based dentro da mesma disciplina.',
+        'next sem handoff exige --activities N (1..200), correspondente ao activityTarget da nova Meta.',
+        'analyze --web e next --web criam apenas rascunhos; create/next --draft exigem status REVIEWED.',
+        'review <draftId> [--wait] [--out payload.json] lê o status e exporta somente o payload já revisado.',
+        'result usa --total N --correct N [--seconds N] [--errors FORGETTING:2,INATTENTION:1].',
+        'Regravação sem --seconds/--errors preserva os valores atuais; no backend, errors omitido preserva e errors: [] limpa.',
+    ],
+};
+function maturity(value, programIndex) {
+    if (typeof value !== 'string') {
+        fail(`programs[${programIndex}].maturity é obrigatória: use BEGINNER, INTERMEDIATE ou ADVANCED.`);
+    }
+    const key = normalized(value);
+    const aliases = {
+        BEGINNER: 'BEGINNER',
+        INICIANTE: 'BEGINNER',
+        INTERMEDIATE: 'INTERMEDIATE',
+        INTERMEDIARIO: 'INTERMEDIATE',
+        ADVANCED: 'ADVANCED',
+        AVANCADO: 'ADVANCED',
+    };
+    const parsed = aliases[key];
+    if (!parsed) {
+        fail(`programs[${programIndex}].maturity inválida: use Iniciante, Intermediário ou Avançado.`);
+    }
+    return parsed;
+}
+export function planPayload(value) {
+    const body = object(value, 'a proposta deve ser um objeto JSON.');
+    if (typeof body.name !== 'string' || body.name.trim() === '') {
+        fail('a proposta precisa de name não vazio.');
+    }
+    if (!Array.isArray(body.programs) || body.programs.length < 1 || body.programs.length > 8) {
+        fail('a proposta precisa de programs com 1 a 8 disciplinas.');
+    }
+    const programs = body.programs.map((programValue, index) => {
+        const program = object(programValue, `programs[${index}] deve ser um objeto.`);
+        if (typeof program.subjectName !== 'string' || program.subjectName.trim() === '') {
+            fail(`programs[${index}].subjectName é obrigatório.`);
+        }
+        if (!Array.isArray(program.topics) || program.topics.length === 0) {
+            fail(`programs[${index}] precisa de ao menos um assunto em topics.`);
+        }
+        return { ...program, maturity: maturity(program.maturity, index) };
+    });
+    return { ...body, name: body.name.trim(), programs };
+}
+export function planBody(file) {
+    return planPayload(readJson(file));
+}
+function analysisDraft(proposal) {
+    const materialsByName = new Map(proposal.materials.map((material) => [material.sourceName, material]));
+    const programs = proposal.subjects.map((subject, subjectIndex) => {
+        const sourceNames = [...new Set(subject.topics.map((topic) => topic.sourceName))];
+        const materials = sourceNames.map((sourceName, materialIndex) => {
+            const source = materialsByName.get(sourceName);
+            const topics = subject.topics.filter((topic) => topic.sourceName === sourceName);
+            const confidence = topics.length
+                ? Math.round((topics.reduce((sum, topic) => sum + topic.confidence, 0) / topics.length) * 100) / 100
+                : undefined;
+            const warnings = [
+                ...(subjectIndex === 0 && materialIndex === 0 ? (proposal.warnings ?? []) : []),
+                ...(subject.warnings ?? []),
+                ...topics.flatMap((topic) => topic.warnings ?? []),
+            ];
+            return {
+                name: sourceName,
+                pageCount: source?.pageCount ?? 0,
+                charCount: source?.charCount ?? topics.reduce((sum, topic) => sum + topic.charCount, 0),
+                confidence,
+                warnings: [...new Set(warnings)],
+            };
+        });
+        return {
+            subjectName: subject.name,
+            maturity: 'BEGINNER',
+            relevance: 3,
+            materials,
+            topics: subject.topics.map((topic) => ({
+                title: topic.title,
+                materialIndex: Math.max(0, sourceNames.indexOf(topic.sourceName)),
+                sourceName: topic.sourceName,
+                pageFrom: topic.pageFrom,
+                pageTo: topic.pageTo,
+                charCount: topic.charCount,
+                estimatedMinutes: topic.estimatedMinutes,
+            })),
+        };
+    });
+    return {
+        name: 'Planejamento de estudos',
+        activeSubjectLimit: Math.min(4, programs.length),
+        programs,
+    };
+}
+async function pollAnalysis(jobId) {
+    const deadline = Date.now() + ANALYSIS_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        const job = (await apiFetch(`/planning/analysis/${jobId}`));
+        if (job.status === 'PROPOSED') {
+            if (!job.proposal) {
+                fail('a análise terminou sem uma proposta.');
+            }
+            return job;
+        }
+        if (job.status === 'FAILED') {
+            fail(`a análise falhou: ${job.error ?? 'erro não informado pelo servidor'}`);
+        }
+        if (job.status !== 'RUNNING') {
+            fail(`status desconhecido da análise: ${String(job.status)}`);
+        }
+        await new Promise((resolveDelay) => setTimeout(resolveDelay, ANALYSIS_POLL_INTERVAL_MS));
+    }
+    fail('a análise demorou mais de 10 minutos; tente consultar novamente com PDFs menores.');
+}
+export async function analyze(parsed, files) {
+    if (files.length === 0) {
+        fail('informe ao menos um PDF: memoring plan analyze <arquivo.pdf...>.');
+    }
+    if (files.length > MAX_ANALYSIS_FILES) {
+        fail(`envie no máximo ${MAX_ANALYSIS_FILES} PDFs por análise.`);
+    }
+    const fileNames = new Set();
+    for (const file of files) {
+        const fileName = basename(resolve(file));
+        if (fileNames.has(fileName)) {
+            fail(`nome de arquivo duplicado: ${fileName}; renomeie um dos PDFs antes do upload.`);
+        }
+        fileNames.add(fileName);
+    }
+    const uploads = await Promise.all(files.map(async (file) => {
+        const path = resolve(file);
+        if (extname(path).toLowerCase() !== '.pdf') {
+            fail(`tipo de arquivo não suportado: ${file} (envie somente PDFs).`);
+        }
+        let size;
+        try {
+            size = statSync(path).size;
+        }
+        catch (error) {
+            fail(`não foi possível abrir ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (size === 0) {
+            fail(`o PDF está vazio: ${file}.`);
+        }
+        if (size > MAX_PDF_BYTES) {
+            fail(`PDF acima de 50 MB: ${file}.`);
+        }
+        return {
+            fieldName: 'files',
+            fileName: basename(path),
+            contentType: 'application/pdf',
+            data: await openAsBlob(path, { type: 'application/pdf' }),
+        };
+    }));
+    if (!parsed.flags.json) {
+        process.stderr.write(`Enviando ${uploads.length} PDF(s) para análise no Memoring…\n`);
+    }
+    const started = (await apiFetchMultipart('/planning/analysis', uploads));
+    if (!started.jobId) {
+        fail('o servidor não devolveu o jobId da análise.');
+    }
+    const job = await pollAnalysis(started.jobId);
+    const draft = analysisDraft(job.proposal);
+    const output = stringFlag(parsed.flags, 'out');
+    if (output) {
+        writeFileSync(resolve(output), `${JSON.stringify(draft, null, 2)}\n`, 'utf8');
+    }
+    if (parsed.flags.web) {
+        await createDraftHandoff('PLAN', null, draft, parsed);
+        return;
+    }
+    if (parsed.flags.json) {
+        printJson(draft);
+        return;
+    }
+    const subjects = job.proposal.subjects.length;
+    const topics = job.proposal.subjects.reduce((sum, subject) => sum + subject.topics.length, 0);
+    process.stdout.write(green(`Análise concluída: ${subjects} disciplina(s), ${topics} assunto(s).\n`));
+    if (output) {
+        process.stdout.write(`Proposta salva em ${output}.\n`);
+    }
+    else {
+        process.stdout.write('Use --out proposta.json para salvar a proposta editável.\n');
+    }
+    process.stdout.write(yellow('Revise nome, maturidade de cada disciplina, tempo semanal, baralhos e assuntos antes de criar.\n') +
+        `Depois rode: memoring plan create --file ${output ?? 'proposta.json'}\n`);
+}

package/dist/commands/plan-diagnostics.js

@@ -0,0 +1,65 @@
+import { apiFetch } from '../api.js';
+import { bold, printJson, printTable } from './shared.js';
+import { ERROR_LABELS, STATUS_LABELS, formatPercent, formatSeconds, } from './plan-shared.js';
+export async function diagnostics(sub, planId, json) {
+    const data = (await apiFetch(`/planning/${planId}/${sub}`));
+    if (json) {
+        printJson(data);
+        return;
+    }
+    if (sub === 'performance') {
+        process.stdout.write(bold(`Desempenho do planejamento #${planId}\n`));
+        process.stdout.write(`${String(data.correctCount)}/${String(data.questionCount)} corretas — ${formatPercent(data.accuracyPercent)}; ` +
+            `${String(data.errorCount)} erros; ${formatSeconds(data.actualSeconds)} registrados.\n`);
+        const subjects = Array.isArray(data.subjects) ? data.subjects : [];
+        printTable(subjects.map((subject) => ({
+            subject: subject.subjectName,
+            result: `${String(subject.correctCount)}/${String(subject.questionCount)}`,
+            accuracy: formatPercent(subject.accuracyPercent),
+            average: formatSeconds(subject.averageSecondsPerQuestion),
+        })), [
+            { key: 'subject', label: 'DISCIPLINA' },
+            { key: 'result', label: 'ACERTOS' },
+            { key: 'accuracy', label: 'DESEMPENHO' },
+            { key: 'average', label: 'TEMPO/QUESTÃO' },
+        ]);
+        return;
+    }
+    if (sub === 'error-patterns') {
+        process.stdout.write(bold(`Padrões de erro do planejamento #${planId}\n`));
+        process.stdout.write(`${String(data.totalErrors)} erros; ${String(data.classifiedErrors)} classificados ` +
+            `(${formatPercent(data.classificationCoveragePercent)}); ${String(data.unclassifiedErrors)} sem classificação.\n`);
+        const reasons = Array.isArray(data.reasons) ? data.reasons : [];
+        printTable(reasons.map((entry) => ({
+            reason: ERROR_LABELS[String(entry.reason)] ?? entry.reason,
+            count: entry.count,
+        })), [{ key: 'reason', label: 'MOTIVO' }, { key: 'count', label: 'ERROS' }]);
+        return;
+    }
+    if (sub === 'comparison') {
+        process.stdout.write(bold(`Comparação do planejamento #${planId}\n`));
+        process.stdout.write(`Meta atual: ${formatPercent(data.currentAccuracyPercent)}\n`);
+        process.stdout.write(`Média das Metas anteriores: ${formatPercent(data.previousAverageAccuracyPercent)}\n`);
+        process.stdout.write(`Referência: ${formatPercent(data.referenceAccuracyPercent)}\n`);
+        process.stdout.write(`Variação: ${typeof data.deltaFromPreviousPercent === 'number' ? `${data.deltaFromPreviousPercent >= 0 ? '+' : ''}${data.deltaFromPreviousPercent.toFixed(2).replace('.', ',')} p.p. vs anterior` : '—'}; ` +
+            `${typeof data.deltaFromReferencePercent === 'number' ? `${data.deltaFromReferencePercent >= 0 ? '+' : ''}${data.deltaFromReferencePercent.toFixed(2).replace('.', ',')} p.p. vs referência` : '—'}.\n`);
+        return;
+    }
+    const goals = Array.isArray(data.goals) ? data.goals : [];
+    process.stdout.write(bold(`Jornada do planejamento #${planId}\n`));
+    printTable(goals.map((goal) => ({
+        goal: `#${String(goal.goalNumber)}`,
+        status: STATUS_LABELS[String(goal.status)] ?? goal.status,
+        activities: `${String(goal.completedActivities)}/${String(goal.activityTarget)}`,
+        result: `${String(goal.correctCount)}/${String(goal.questionCount)}`,
+        accuracy: formatPercent(goal.accuracyPercent),
+        seconds: formatSeconds(goal.actualSeconds),
+    })), [
+        { key: 'goal', label: 'META' },
+        { key: 'status', label: 'STATUS' },
+        { key: 'activities', label: 'ATIVIDADES' },
+        { key: 'result', label: 'ACERTOS' },
+        { key: 'accuracy', label: 'DESEMPENHO' },
+        { key: 'seconds', label: 'TEMPO' },
+    ]);
+}