@memoring/cli 0.13.0 → 0.15.0

package/dist/commands/batch.js

@@ -0,0 +1,327 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { apiFetch } from '../api.js';
+import { listDecks } from './deck.js';
+import { fail, green, printJson, yellow } from './shared.js';
+const MAIN_PATH = fileURLToPath(new URL('../main.js', import.meta.url));
+function parseJsonFile(filePath) {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+}
+function batchItems(filePath) {
+    const payload = parseJsonFile(filePath);
+    return Array.isArray(payload) ? payload : payload.items;
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function loadPlan(planPath) {
+    const raw = readFileSync(planPath, 'utf8');
+    const plan = JSON.parse(raw);
+    if (plan.version !== 1 || !Array.isArray(plan.activities) || plan.activities.length === 0) {
+        fail('manifesto inválido: esperado version=1 e activities não vazio.');
+    }
+    if (typeof plan.pdfMap !== 'object' || plan.pdfMap === null || Array.isArray(plan.pdfMap)) {
+        fail('manifesto inválido: pdfMap deve ser um objeto driveFileId → PDF local.');
+    }
+    const base = dirname(resolve(planPath));
+    const ids = new Set();
+    for (const [index, activity] of plan.activities.entries()) {
+        const where = `atividade #${index + 1}`;
+        if (!activity.id || ids.has(activity.id))
+            fail(`${where}: id ausente ou duplicado (${activity.id}).`);
+        ids.add(activity.id);
+        if (!activity.batchFile || !activity.deckName)
+            fail(`${where} (${activity.id}): batchFile/deckName obrigatórios.`);
+        activity.batchFile = resolve(base, activity.batchFile);
+        if (activity.generationFile)
+            activity.generationFile = resolve(base, activity.generationFile);
+        if (!Array.isArray(activity.expectedReferences))
+            activity.expectedReferences = [];
+    }
+    for (const [id, file] of Object.entries(plan.pdfMap)) {
+        if (typeof file !== 'string' || file.trim() === '')
+            fail(`pdfMap.${id}: caminho inválido.`);
+        plan.pdfMap[id] = resolve(base, file);
+    }
+    return { plan, raw };
+}
+function strictDeck(decks, ref, activityId) {
+    const numeric = Number(ref);
+    const matches = Number.isInteger(numeric) && numeric > 0
+        ? decks.filter((deck) => deck.id === numeric)
+        : decks.filter((deck) => deck.name.trim().toLocaleLowerCase('pt-BR') === ref.trim().toLocaleLowerCase('pt-BR'));
+    if (matches.length === 0) {
+        throw new Error(`${activityId}: baralho ${ref} não existe; crie-o explicitamente antes do batch.`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`${activityId}: baralho ${ref} é ambíguo (${matches.map((deck) => `#${deck.id}`).join(', ')}); use o ID.`);
+    }
+    return matches[0];
+}
+async function runCliJson(args) {
+    return new Promise((resolvePromise, reject) => {
+        execFile(process.execPath, [MAIN_PATH, ...args, '--json', '--no-color'], {
+            env: { ...process.env, MEMORING_NO_UPDATE_CHECK: '1' },
+            encoding: 'utf8',
+            maxBuffer: 32 * 1024 * 1024,
+        }, (error, stdout, stderr) => {
+            const code = error && typeof error.code === 'number'
+                ? Number(error.code)
+                : error ? 1 : 0;
+            try {
+                resolvePromise({ code, data: JSON.parse(stdout), stdout, stderr });
+            }
+            catch {
+                reject(new Error(`CLI retornou saída inválida (${args.join(' ')}): ${stderr || stdout || error?.message}`));
+            }
+        });
+    });
+}
+function pageRange(raw) {
+    const match = /^(\d+)(?:-(\d+))?$/.exec(raw);
+    if (!match)
+        throw new Error(`faixa de páginas inválida: ${raw}`);
+    const from = Number(match[1]);
+    const to = Number(match[2] ?? match[1]);
+    if (from < 1 || to < from)
+        throw new Error(`faixa de páginas inválida: ${raw}`);
+    return { from, to };
+}
+function writeJsonAtomic(filePath, value) {
+    const temp = `${filePath}.${process.pid}.tmp`;
+    writeFileSync(temp, JSON.stringify(value, null, 2));
+    renameSync(temp, filePath);
+}
+async function checkPlan(planPath, plan) {
+    const errors = [];
+    const warnings = [];
+    const checked = [];
+    const pdfMapFile = `${planPath}.pdf-map.json`;
+    writeJsonAtomic(pdfMapFile, plan.pdfMap);
+    let decks;
+    try {
+        decks = await listDecks();
+    }
+    catch (error) {
+        return { valid: false, errors: [`não consegui listar os baralhos: ${error.message}`], warnings, activities: [], pdfMapFile };
+    }
+    for (const activity of plan.activities) {
+        let deck;
+        try {
+            deck = strictDeck(decks, activity.deckName, activity.id);
+        }
+        catch (error) {
+            errors.push(error.message);
+            continue;
+        }
+        if (!existsSync(activity.batchFile)) {
+            errors.push(`${activity.id}: batchFile não encontrado (${activity.batchFile}).`);
+            continue;
+        }
+        if (activity.generationFile && !existsSync(activity.generationFile)) {
+            errors.push(`${activity.id}: generationFile não encontrado (${activity.generationFile}).`);
+            continue;
+        }
+        const items = batchItems(activity.batchFile);
+        for (const [index, item] of items.entries()) {
+            if (item.deckName !== activity.deckName) {
+                errors.push(`${activity.id}, item #${index + 1} (${item.title}): deckName ${item.deckName} difere de ${activity.deckName}.`);
+            }
+            for (const reference of item.materialReferences ?? []) {
+                if (activity.expectedReferences.length === 0)
+                    continue;
+                const matches = activity.expectedReferences.some((expected) => {
+                    if (expected.driveFileId !== reference.driveFileId)
+                        return false;
+                    const range = pageRange(expected.pages);
+                    return reference.page >= range.from && reference.page <= range.to;
+                });
+                if (!matches) {
+                    errors.push(`${activity.id}, item #${index + 1} (${item.title}): referência ${reference.driveFileId} página ${reference.page} fora do esperado.`);
+                }
+            }
+        }
+        const validation = await runCliJson(['stage', 'validate', '--file', activity.batchFile, '--pdf-map', pdfMapFile]);
+        if (!validation.data.valid) {
+            errors.push(...(validation.data.errors ?? []).map((error) => `${activity.id}: ${error}`));
+        }
+        warnings.push(...(validation.data.warnings ?? []).map((warning) => `${activity.id}: ${warning}`));
+        checked.push({
+            ...activity,
+            deckId: deck.id,
+            items,
+            batchHash: sha256(readFileSync(activity.batchFile, 'utf8')),
+        });
+    }
+    return { valid: errors.length === 0, errors, warnings, activities: checked, pdfMapFile };
+}
+function statePath(planPath) {
+    return `${planPath}.state.json`;
+}
+function loadState(planPath, planHash) {
+    const path = statePath(planPath);
+    if (!existsSync(path))
+        return { version: 1, planHash, activities: {} };
+    let state;
+    try {
+        state = parseJsonFile(path);
+    }
+    catch (error) {
+        fail(`state corrompido (${path}): ${error.message}`);
+    }
+    if (state.version !== 1 || state.planHash !== planHash || typeof state.activities !== 'object') {
+        fail(`state incompatível com o manifesto (${path}); revise-o ou use outro manifesto.`);
+    }
+    return state;
+}
+async function verifyActivities(activities, state) {
+    const errors = [];
+    const inbox = (await apiFetch('/notes/review-inbox'));
+    const byId = new Map(inbox.map((note) => [note.id, note]));
+    for (const activity of activities) {
+        const current = state.activities[activity.id];
+        if (!current) {
+            errors.push(`${activity.id}: ainda não foi estagiada.`);
+            continue;
+        }
+        if (current.ids.length !== activity.items.length) {
+            errors.push(`${activity.id}: ${current.ids.length} IDs para ${activity.items.length} itens.`);
+            continue;
+        }
+        for (const [index, noteId] of current.ids.entries()) {
+            const note = byId.get(noteId);
+            if (!note) {
+                errors.push(`${activity.id}: nota #${noteId} ausente da caixa de revisão.`);
+                continue;
+            }
+            if (note.deckId !== activity.deckId) {
+                errors.push(`${activity.id}/${noteId}: deckId ${note.deckId}, esperado ${activity.deckId}.`);
+            }
+            const body = (await apiFetch(`/notes/${noteId}/material-references`));
+            const expected = activity.items[index].materialReferences ?? [];
+            const actual = body.references;
+            if (actual.length !== expected.length) {
+                errors.push(`${activity.id}/${noteId}: ${actual.length} referências, esperado ${expected.length}.`);
+                continue;
+            }
+            for (const [refIndex, reference] of actual.entries()) {
+                const source = expected[refIndex];
+                if (reference.driveFileId !== source.driveFileId ||
+                    reference.pageIndex + 1 !== source.page ||
+                    (reference.quote ?? undefined) !== source.quote ||
+                    (reference.contextBefore ?? undefined) !== source.contextBefore ||
+                    (reference.contextAfter ?? undefined) !== source.contextAfter ||
+                    JSON.stringify(reference.region ?? null) !== JSON.stringify(source.region ?? null)) {
+                    errors.push(`${activity.id}/${noteId}: referência #${refIndex + 1} divergente.`);
+                }
+            }
+        }
+        if (current.importRunId) {
+            const run = (await apiFetch(`/notes/import-runs/${current.importRunId}`));
+            const linked = new Set(run.noteIds);
+            for (const noteId of current.ids) {
+                if (!linked.has(noteId))
+                    errors.push(`${activity.id}: nota #${noteId} ausente no import run ${current.importRunId}.`);
+            }
+        }
+    }
+    return errors;
+}
+function emit(parsed, result, valid) {
+    if (parsed.flags.json) {
+        printJson(result);
+    }
+    else {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    }
+    if (!valid)
+        process.exitCode = 1;
+}
+export async function batchCommand(parsed) {
+    const [sub, planArg] = parsed._;
+    if (!sub || !planArg) {
+        fail('uso: memoring batch <check|run|status|verify> plan.json [--resume] [--json]');
+    }
+    const planPath = resolve(planArg);
+    if (sub === 'status') {
+        const { raw } = loadPlan(planPath);
+        const state = loadState(planPath, sha256(raw));
+        emit(parsed, state, true);
+        return;
+    }
+    const { plan, raw } = loadPlan(planPath);
+    if (sub === 'check') {
+        const result = await checkPlan(planPath, plan);
+        emit(parsed, result, result.valid);
+        return;
+    }
+    if (sub === 'verify') {
+        const checked = await checkPlan(planPath, plan);
+        if (!checked.valid) {
+            emit(parsed, checked, false);
+            return;
+        }
+        const state = loadState(planPath, sha256(raw));
+        const errors = await verifyActivities(checked.activities, state);
+        emit(parsed, { valid: errors.length === 0, errors }, errors.length === 0);
+        return;
+    }
+    if (sub !== 'run') {
+        fail(`subcomando inválido: ${sub}; use check, run, status ou verify.`);
+    }
+    const checked = await checkPlan(planPath, plan);
+    if (!checked.valid) {
+        emit(parsed, checked, false);
+        return;
+    }
+    const state = loadState(planPath, sha256(raw));
+    for (const activity of checked.activities) {
+        let current = state.activities[activity.id];
+        if (current && current.batchHash !== activity.batchHash) {
+            fail(`${activity.id}: o lote mudou desde o último envio; revise o state antes de continuar.`);
+        }
+        if (current?.status === 'verified' && parsed.flags.resume) {
+            continue;
+        }
+        if (!current || current.ids.length !== activity.items.length) {
+            const args = ['stage', 'create', '--file', activity.batchFile];
+            if (activity.generationFile)
+                args.push('--generation-file', activity.generationFile);
+            const created = await runCliJson(args);
+            if (created.code !== 0) {
+                fail(`${activity.id}: stage create falhou: ${created.stderr || created.stdout}`);
+            }
+            if (!Array.isArray(created.data.ids)) {
+                fail(`${activity.id}: stage create não devolveu os IDs esperados.`);
+            }
+            current = {
+                batchHash: activity.batchHash,
+                deckId: activity.deckId,
+                ids: created.data.ids,
+                importRunId: created.data.importRunId ?? null,
+                status: 'staged',
+                updatedAt: new Date().toISOString(),
+            };
+            state.activities[activity.id] = current;
+            writeJsonAtomic(statePath(planPath), state);
+        }
+    }
+    const errors = await verifyActivities(checked.activities, state);
+    if (errors.length === 0) {
+        for (const activity of checked.activities) {
+            state.activities[activity.id].status = 'verified';
+            state.activities[activity.id].updatedAt = new Date().toISOString();
+        }
+        writeJsonAtomic(statePath(planPath), state);
+    }
+    emit(parsed, { valid: errors.length === 0, errors, state }, errors.length === 0);
+    if (errors.length === 0 && !parsed.flags.json) {
+        process.stdout.write(green('Batch enviado e conferido.\n'));
+    }
+    else if (errors.length > 0) {
+        process.stderr.write(yellow(`${errors.length} divergência(s) na auditoria.\n`));
+    }
+}

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;
+            }
+    }
+}