@memoring/cli 0.13.0 → 0.15.0

package/dist/commands/scratch.js

@@ -0,0 +1,632 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { basename, dirname, join, resolve } from 'node:path';
+import { PDFDocument } from 'pdf-lib';
+import { apiFetch, apiFetchBytes, ApiError } from '../api.js';
+import { CliError } from '../output.js';
+import { dim, fail, green, printJson, printTable, stringFlag, yellow } from './shared.js';
+/**
+ * Rascunhos do caderno manuscrito (proxy Drive do backend — fase P2): a CLI
+ * lista/baixa os `.scratch.json` + o PDF de fundo (assets dedupados por hash)
+ * e recorta o PDF por faixa de páginas antes da geração de flashcards. A CLI
+ * NÃO inicia o OAuth do Google — isso é feito pelo app; desconectado, o proxy
+ * devolve 409 e o comando orienta o usuário a conectar pelo app.
+ */
+/** Estimativa de tokens de prompt por página densa de PDF (medido em prod 2026-10, espelha o app). */
+export const TOKENS_PER_PAGE_ESTIMATE = 2700;
+/** Acima de ~30 páginas, o `extract` exige --all explícito ou um recorte --pages (forcing function). */
+export const EXTRACT_FORCE_ALL_MIN_PAGES = 30;
+/** "113,4 mil tokens" (espelha o formatTokens do app); abaixo de 1 mil, o número cru. */
+export function formatTokens(total) {
+    if (total < 1000) {
+        return `${total} tokens`;
+    }
+    const rounded = total < 100_000 ? Math.round(total / 100) / 10 : Math.round(total / 1000);
+    return `${String(rounded).replace('.', ',')} mil tokens`;
+}
+/** Nome de arquivo: minúsculo, sem acentos, não-alfanumérico vira hífen, teto de 60 chars. */
+export function slugifyTitle(title) {
+    const slug = title
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60)
+        .replace(/-+$/g, '');
+    return slug || 'rascunho';
+}
+/**
+ * Comparação de caminhos: NFD, sem acento, minúsculo, espaços colapsados e
+ * aspas externas removidas — o usuário digita case/acentos/espaços livres.
+ */
+function normalizePathText(value) {
+    return value
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/^["']+|["']+$/g, '');
+}
+/** "Aula 02" ou "Pasta/Aula 02" (ou com backslash) → segmentos normalizados e não-vazios. */
+function splitPathArg(raw) {
+    return raw
+        .split(/[\\/]+/)
+        .map(normalizePathText)
+        .filter((seg) => seg !== '');
+}
+/** Nomes da cadeia de pastas (raiz → folha); tolera ciclo/pasta órfã sem travar. */
+function folderBreadcrumb(folderId, folderMap) {
+    const names = [];
+    const seen = new Set();
+    let current = folderId ?? null;
+    while (current !== null && !seen.has(current)) {
+        seen.add(current);
+        const folder = folderMap.get(current);
+        if (!folder) {
+            break; // pasta órfã (apagada/offline) — para no que achou
+        }
+        names.unshift(folder.name);
+        current = folder.parentId;
+    }
+    return names;
+}
+/**
+ * Caminho legível do documento na biblioteca: breadcrumb da pasta + título
+ * (cada documento é pasta-folha). CARD_SCRATCH vive fora da árvore, em
+ * "Rascunhos de cards/<noteId|título>".
+ */
+function docPathSegments(doc, folderMap) {
+    if (doc.kind === 'CARD_SCRATCH') {
+        return ['Rascunhos de cards', String(doc.linkedNoteId ?? doc.title)];
+    }
+    return [...folderBreadcrumb(doc.folderId, folderMap), doc.title];
+}
+function docPath(doc, folderMap) {
+    return docPathSegments(doc, folderMap).join('/');
+}
+/**
+ * Resolve o argumento do `download` como caminho completo da biblioteca.
+ * Só aceita correspondência exata (normalizada) — sem chute: não encontrado
+ * ou ambíguo vira erro acionável listando os candidatos.
+ */
+function resolveDocByPath(raw, documents, folderMap) {
+    const wanted = splitPathArg(raw);
+    if (wanted.length === 0) {
+        fail('caminho vazio — informe o caminho completo do rascunho (veja `memoring scratch list`).');
+    }
+    const wantedKey = wanted.join('/');
+    const byPath = new Map();
+    for (const doc of documents) {
+        const key = docPathSegments(doc, folderMap).map(normalizePathText).join('/');
+        const list = byPath.get(key) ?? [];
+        list.push(doc);
+        byPath.set(key, list);
+    }
+    const exact = byPath.get(wantedKey) ?? [];
+    if (exact.length === 1) {
+        return exact[0];
+    }
+    if (exact.length > 1) {
+        const candidates = exact
+            .map((d) => `  - ${docPath(d, folderMap)} (driveFileId ${d.driveFileId})`)
+            .join('\n');
+        fail(`o caminho ${JSON.stringify(raw)} é ambíguo — ${exact.length} rascunhos usam esse caminho:\n` +
+            `${candidates}\nrefine o caminho (a pasta) ou use o driveFileId.`);
+    }
+    const folderHits = [...folderMap.values()].filter((f) => folderBreadcrumb(f.id, folderMap).map(normalizePathText).join('/') === wantedKey);
+    if (folderHits.length > 0) {
+        const children = documents
+            .filter((d) => d.kind !== 'CARD_SCRATCH' &&
+            folderBreadcrumb(d.folderId, folderMap).map(normalizePathText).join('/') === wantedKey)
+            .map((d) => `  - ${docPath(d, folderMap)} (driveFileId ${d.driveFileId})`);
+        fail(`o caminho ${JSON.stringify(raw)} é uma pasta da biblioteca, não um rascunho.` +
+            (children.length > 0
+                ? `\ndocumentos diretamente nela:\n${children.join('\n')}`
+                : '\n(nenhum documento diretamente nela)') +
+            '\nbaixe pelo caminho completo do documento (veja `memoring scratch list`).');
+    }
+    const suffix = documents.filter((d) => {
+        const segs = docPathSegments(d, folderMap).map(normalizePathText);
+        return segs.length >= wanted.length && segs.slice(segs.length - wanted.length).join('/') === wantedKey;
+    });
+    const candidateLines = suffix
+        .slice(0, 10)
+        .map((d) => `  - ${docPath(d, folderMap)}`)
+        .join('\n');
+    fail(`nenhum rascunho bate com ${JSON.stringify(raw)} — nem como caminho completo nem como driveFileId.` +
+        (candidateLines ? `\ncandidatos com esse final de caminho:\n${candidateLines}` : '') +
+        '\nconfira os caminhos com `memoring scratch list` (use --all para incluir rascunhos de card).');
+}
+/** Nome local do PDF: basename legível sanitizado (slug sem acento, extensão .pdf preservada). */
+function sanitizePdfFileName(name, fallback) {
+    if (typeof name !== 'string' || name.trim() === '') {
+        return fallback;
+    }
+    const base = name
+        .trim()
+        .replace(/\\/g, '/')
+        .split('/')
+        .pop()
+        .replace(/\.pdf$/i, '');
+    const slug = base
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60)
+        .replace(/-+$/g, '');
+    return slug === '' ? fallback : `${slug}.pdf`;
+}
+/** "A-B" / "A" (aceita hífen e travessão) → faixa 1-based validada contra o pageCount. */
+export function parsePageRange(raw, pageCount) {
+    const match = /^(\d+)(?:\s*[-–—]\s*(\d+))?$/.exec(raw.trim());
+    if (!match) {
+        fail(`--pages inválido: use "A-B" (ex.: 20-35) ou "A" (página única) — veio ${JSON.stringify(raw)}.`);
+    }
+    const from = Number(match[1]);
+    const to = match[2] !== undefined ? Number(match[2]) : from;
+    if (from < 1) {
+        fail(`a faixa começa na página ${from} — as páginas são numeradas de 1 a ${pageCount}.`);
+    }
+    if (from > pageCount) {
+        fail(`página inicial ${from} além do fim do PDF — o arquivo tem só ${pageCount} página(s).`);
+    }
+    if (to < from) {
+        fail(`a página final (${to}) deve ser maior ou igual à inicial (${from}).`);
+    }
+    return { from, to: Math.min(to, pageCount), clampedTo: to > pageCount };
+}
+function fmtUpdated(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime())) {
+        return iso;
+    }
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+/** Erros do proxy Drive em mensagens acionáveis. */
+function rethrowDownloadError(e, what) {
+    if (e instanceof ApiError) {
+        if (e.status === 409) {
+            fail(`o Google Drive não está conectado à sua conta (409 ${e.body}) — conecte pelo app ` +
+                '(Caderno → vincular Drive) e tente de novo. A CLI não inicia o OAuth do Google.');
+        }
+        if (e.status === 404) {
+            fail(`${what}: arquivo não encontrado no Drive (404 ${e.body}) — confira o id com \`memoring scratch list\`.`);
+        }
+        fail(`falha ao ${what} (${e.status}): ${e.body}`);
+    }
+    throw e;
+}
+async function listScratchDocuments() {
+    const res = (await apiFetch('/handwriting/documents'));
+    return Array.isArray(res?.documents) ? res.documents : [];
+}
+async function listScratchFolders() {
+    try {
+        const res = (await apiFetch('/handwriting/folders'));
+        return Array.isArray(res?.folders) ? res.folders : [];
+    }
+    catch (e) {
+        // backend sem V233: o caminho degrada para "só o título" em vez de derrubar o comando
+        if (e instanceof ApiError && e.status === 404) {
+            return [];
+        }
+        throw e;
+    }
+}
+/** Documentos + pastas da biblioteca (as duas âncoras do caminho legível). */
+async function fetchScratchLibrary() {
+    const [documents, folders] = await Promise.all([listScratchDocuments(), listScratchFolders()]);
+    return { documents, folderMap: new Map(folders.map((f) => [f.id, f])) };
+}
+async function scratchList(parsed) {
+    const includeAll = parsed.flags.all === true;
+    const { documents, folderMap } = await fetchScratchLibrary();
+    const docs = documents
+        .filter((d) => includeAll || d.kind === 'FREE_NOTEBOOK')
+        .sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)))
+        .map((d) => ({ ...d, path: docPath(d, folderMap) }));
+    if (parsed.flags.json) {
+        printJson(docs);
+        return;
+    }
+    if (docs.length === 0) {
+        process.stdout.write(includeAll ? 'Nenhum rascunho encontrado.\n' : 'Nenhum caderno encontrado (use --all para incluir rascunhos de card).\n');
+        return;
+    }
+    const columns = [
+        { key: 'path', label: 'CAMINHO' },
+        ...(includeAll ? [{ key: 'kind', label: 'TIPO' }] : []),
+        { key: 'updatedAt', label: 'ATUALIZADO' },
+        { key: 'driveFileId', label: 'DRIVE FILE ID' },
+    ];
+    printTable(docs.map((d) => ({
+        path: d.path,
+        ...(includeAll ? { kind: d.kind } : {}),
+        updatedAt: fmtUpdated(d.updatedAt),
+        driveFileId: d.driveFileId,
+    })), columns);
+    process.stdout.write(`\n${docs.length} rascunho(s) — baixe com \`memoring scratch download <caminho>\` ` +
+        `(ex.: \`memoring scratch download "${docs[0].path}"\`).\n`);
+}
+async function scratchDownload(parsed) {
+    const targetArg = parsed._[1];
+    if (!targetArg) {
+        fail('informe o caminho ou o driveFileId: memoring scratch download <caminho|driveFileId> [--out <dir>] ' +
+            '(veja `memoring scratch list`).');
+    }
+    const outDir = resolve(stringFlag(parsed.flags, 'out') ?? '.');
+    const metadataOnly = parsed.flags['metadata-only'] === true;
+    // Âncora local (título/kind/caminho) — best-effort: resolve caminho → driveFileId
+    // quando a biblioteca responde; sem ela, o argumento é tratado como driveFileId
+    // (comportamento das versões anteriores).
+    let anchor;
+    let anchorPath = null;
+    try {
+        const { documents, folderMap } = await fetchScratchLibrary();
+        anchor = documents.find((d) => d.driveFileId === targetArg);
+        if (!anchor) {
+            anchor = resolveDocByPath(targetArg, documents, folderMap);
+        }
+        anchorPath = docPath(anchor, folderMap);
+    }
+    catch (e) {
+        if (e instanceof CliError) {
+            throw e;
+        }
+        process.stderr.write(dim('aviso: não consegui carregar a biblioteca de rascunhos — tratando o argumento como driveFileId.\n'));
+    }
+    const driveFileId = anchor?.driveFileId ?? targetArg;
+    let jsonBytes;
+    try {
+        jsonBytes = (await apiFetchBytes(`/handwriting/files/${encodeURIComponent(driveFileId)}`)).body;
+    }
+    catch (e) {
+        rethrowDownloadError(e, 'baixar o rascunho');
+    }
+    let doc;
+    try {
+        doc = JSON.parse(jsonBytes.toString('utf8'));
+    }
+    catch {
+        fail('o arquivo baixado não é um .scratch.json válido (JSON ilegível).');
+    }
+    const title = (typeof doc.title === 'string' && doc.title.trim() !== '' && doc.title) ||
+        anchor?.title ||
+        driveFileId;
+    const pdf = (typeof doc.pdf === 'object' && doc.pdf !== null ? doc.pdf : undefined);
+    const pdfDriveFileId = typeof pdf?.driveFileId === 'string' && pdf.driveFileId.trim() !== '' ? pdf.driveFileId : undefined;
+    const pdfAssetHash = typeof pdf?.assetHash === 'string' && pdf.assetHash.trim() !== '' ? pdf.assetHash : undefined;
+    const pdfPageCount = typeof pdf?.pageCount === 'number' && pdf.pageCount > 0 ? pdf.pageCount : undefined;
+    const hasPdf = pdfDriveFileId !== undefined || (pdfAssetHash !== undefined && pdfPageCount !== undefined);
+    mkdirSync(outDir, { recursive: true });
+    const jsonPath = join(outDir, `${slugifyTitle(title)}.scratch.json`);
+    writeFileSync(jsonPath, jsonBytes);
+    const files = { scratchJson: jsonPath };
+    let pdfInfo = null;
+    if (hasPdf && !metadataOnly) {
+        let pdfBytes;
+        let pdfFileId;
+        if (pdfDriveFileId) {
+            try {
+                pdfBytes = (await apiFetchBytes(`/handwriting/files/${encodeURIComponent(pdfDriveFileId)}`)).body;
+                pdfFileId = pdfDriveFileId;
+            }
+            catch (e) {
+                // 404 no arquivo do PDF → fallback pro asset dedupado (rascunhos antigos);
+                // qualquer outro erro (409 desconectado, 5xx) é fatal.
+                if (!(e instanceof ApiError) || e.status !== 404) {
+                    rethrowDownloadError(e, 'baixar o PDF de fundo');
+                }
+            }
+        }
+        if (pdfBytes === undefined && pdfAssetHash) {
+            const assetName = `${pdfAssetHash}.pdf`;
+            let assetFile;
+            try {
+                const res = (await apiFetch(`/handwriting/files?folder=assets&name=${encodeURIComponent(assetName)}`));
+                assetFile = res?.files?.[0];
+            }
+            catch (e) {
+                rethrowDownloadError(e, 'localizar o PDF de fundo');
+            }
+            if (assetFile) {
+                try {
+                    pdfBytes = (await apiFetchBytes(`/handwriting/files/${encodeURIComponent(assetFile.fileId)}`)).body;
+                    pdfFileId = assetFile.fileId;
+                }
+                catch (e) {
+                    rethrowDownloadError(e, 'baixar o PDF de fundo');
+                }
+            }
+        }
+        if (pdfBytes === undefined || pdfFileId === undefined) {
+            const detail = pdfDriveFileId && !pdfAssetHash
+                ? `o arquivo do PDF (driveFileId ${pdfDriveFileId}) não foi encontrado no Drive`
+                : `o asset ${pdfAssetHash}.pdf não foi encontrado na pasta assets`;
+            process.stderr.write(yellow(`aviso: ${detail} — só o .scratch.json foi salvo.\n`));
+        }
+        else {
+            const pdfName = sanitizePdfFileName(pdf?.name, pdfAssetHash ? `${pdfAssetHash}.pdf` : `${slugifyTitle(title)}.pdf`);
+            const pdfPath = join(outDir, pdfName);
+            writeFileSync(pdfPath, pdfBytes);
+            files.pdf = pdfPath;
+            pdfInfo = { assetHash: pdfAssetHash ?? null, pageCount: pdfPageCount, fileId: pdfFileId, path: pdfPath };
+        }
+    }
+    if (parsed.flags.json) {
+        printJson({
+            title,
+            kind: anchor?.kind ?? null,
+            path: anchorPath,
+            driveFileId,
+            files,
+            pdfMetadata: hasPdf
+                ? {
+                    driveFileId: pdfDriveFileId ?? null,
+                    assetHash: pdfAssetHash ?? null,
+                    pageCount: pdfPageCount ?? null,
+                    name: typeof pdf?.name === 'string' ? pdf.name : null,
+                }
+                : null,
+            pdf: pdfInfo
+                ? {
+                    assetHash: pdfInfo.assetHash,
+                    pageCount: pdfInfo.pageCount ?? null,
+                    tokensEstimate: pdfInfo.pageCount !== undefined ? pdfInfo.pageCount * TOKENS_PER_PAGE_ESTIMATE : null,
+                    fileId: pdfInfo.fileId,
+                }
+                : null,
+        });
+        return;
+    }
+    process.stdout.write(green(`Rascunho baixado: "${title}"${anchor?.kind ? ` [${anchor.kind}]` : ''}\n`));
+    process.stdout.write(`  JSON: ${jsonPath}\n`);
+    if (pdfInfo) {
+        if (pdfInfo.pageCount !== undefined) {
+            process.stdout.write(`  PDF:  ${pdfInfo.path} (${pdfInfo.pageCount} ${pdfInfo.pageCount === 1 ? 'página' : 'páginas'}, ` +
+                `≈${formatTokens(pdfInfo.pageCount * TOKENS_PER_PAGE_ESTIMATE)})\n`);
+            if (pdfInfo.pageCount > EXTRACT_FORCE_ALL_MIN_PAGES) {
+                process.stdout.write(yellow(`  PDF com ${pdfInfo.pageCount} páginas (≈${formatTokens(pdfInfo.pageCount * TOKENS_PER_PAGE_ESTIMATE)}). ` +
+                    `Para gerar por faixas: memoring scratch extract ${pdfInfo.path} --pages A-B\n`));
+            }
+        }
+        else {
+            process.stdout.write(`  PDF:  ${pdfInfo.path} (número de páginas desconhecido)\n`);
+        }
+    }
+    else if (metadataOnly && hasPdf) {
+        process.stdout.write(`  PDF (não baixado): ${pdfDriveFileId ?? `asset ${pdfAssetHash}`} — ` +
+            `${pdfPageCount ?? '?'} página(s).\n`);
+    }
+    else {
+        process.stderr.write(yellow('aviso: este rascunho não tem PDF de fundo — só o .scratch.json foi salvo. Gere a partir do conteúdo dele.\n'));
+    }
+    if (!metadataOnly) {
+        process.stdout.write(dim('Próximo passo: memoring scratch extract <arquivo.pdf> --pages A-B (se necessário) → stage create.\n'));
+    }
+}
+async function scratchExtract(parsed) {
+    const fileArg = parsed._[1];
+    if (!fileArg) {
+        fail('informe o PDF: memoring scratch extract <arquivo.pdf> [--pages A-B] [--all] [--text] [--out <alvo>]');
+    }
+    if (!existsSync(fileArg)) {
+        fail(`arquivo não encontrado: ${fileArg}`);
+    }
+    const wantText = parsed.flags.text === true;
+    // pageCount vem do pdf-lib (recorte) ou do pdfjs (--text) — a faixa e a
+    // forcing function são idênticas nos dois caminhos.
+    let pageCount;
+    let srcDoc = null;
+    let textDoc = null;
+    if (wantText) {
+        textDoc = await loadPdfjsDocument(fileArg);
+        pageCount = textDoc.numPages;
+    }
+    else {
+        try {
+            srcDoc = await PDFDocument.load(readFileSync(fileArg));
+        }
+        catch (e) {
+            fail(`não consegui ler o PDF (${fileArg}): ${e.message} — o arquivo é um PDF válido?`);
+        }
+        pageCount = srcDoc.getPageCount();
+    }
+    const pagesRaw = stringFlag(parsed.flags, 'pages');
+    let range;
+    if (pagesRaw !== undefined) {
+        range = parsePageRange(pagesRaw, pageCount);
+        if (range.clampedTo) {
+            process.stderr.write(yellow(`aviso: o PDF tem ${pageCount} página(s) — a faixa foi limitada até ${range.to}.\n`));
+        }
+    }
+    else {
+        if (pageCount > EXTRACT_FORCE_ALL_MIN_PAGES && parsed.flags.all !== true) {
+            fail(`este PDF tem ${pageCount} páginas (≈${formatTokens(pageCount * TOKENS_PER_PAGE_ESTIMATE)}) — confirme com --all ` +
+                'ou recorte com --pages A-B (gerar de um PDF inteiro dessa grossura estoura o contexto do agente).');
+        }
+        range = { from: 1, to: pageCount, clampedTo: false };
+    }
+    if (wantText) {
+        await scratchExtractText(parsed, fileArg, textDoc, range, pageCount);
+        return;
+    }
+    const indices = [];
+    for (let i = range.from - 1; i <= range.to - 1; i++) {
+        indices.push(i);
+    }
+    const outDoc = await PDFDocument.create();
+    const copied = await outDoc.copyPages(srcDoc, indices);
+    for (const page of copied) {
+        outDoc.addPage(page);
+    }
+    const outBytes = await outDoc.save();
+    const explicitOut = stringFlag(parsed.flags, 'out');
+    const outPath = explicitOut
+        ? resolve(explicitOut)
+        : resolve(dirname(fileArg), `${basename(fileArg).replace(/\.pdf$/i, '')}-p${range.from}-${range.to}.pdf`);
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, outBytes);
+    const extractedPages = range.to - range.from + 1;
+    const tokens = extractedPages * TOKENS_PER_PAGE_ESTIMATE;
+    if (parsed.flags.json) {
+        printJson({
+            input: fileArg,
+            output: outPath,
+            pageCount,
+            range: { from: range.from, to: range.to },
+            extractedPages,
+            tokensEstimate: tokens,
+        });
+        return;
+    }
+    process.stdout.write(green(`Recorte salvo em ${outPath}\n`) +
+        `  faixa ${range.from}-${range.to} de ${pageCount} página(s) → ${extractedPages} página(s), ` +
+        `≈${formatTokens(tokens)}\n` +
+        dim('Gere os flashcards a partir DESTE recorte (não do PDF inteiro).\n'));
+}
+/**
+ * Abre o PDF com pdfjs-dist (build legacy — a única build compatível com Node)
+ * para extração de texto. O worker não existe em Node: o pdfjs cai sozinho no
+ * "fake worker" de main thread quando `Worker` está indefinido (comportamento
+ * documentado da versão pinada). `standardFontDataUrl`/`cMapUrl` apontam pros
+ * dados bundled do próprio pacote — sem eles PDFs com fontes standard
+ * não-embedded (ex.: os que o pdf-lib gera) avisam no stderr.
+ */
+async function loadPdfjsDocument(fileArg) {
+    const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs');
+    const require = createRequire(import.meta.url);
+    const packageDir = dirname(require.resolve('pdfjs-dist/package.json'));
+    try {
+        const loadingTask = pdfjs.getDocument({
+            data: new Uint8Array(readFileSync(fileArg)),
+            standardFontDataUrl: `${packageDir}/standard_fonts/`,
+            cMapUrl: `${packageDir}/cmaps/`,
+            cMapPacked: true,
+        });
+        return await loadingTask.promise;
+    }
+    catch (e) {
+        fail(`não consegui ler o PDF (${fileArg}): ${e.message} — o arquivo é um PDF válido?`);
+    }
+}
+/** Texto legível de uma página: itens agrupados por linha (transform[5] ≈ y) e
+ *  ordenados por x — o content stream não preserva quebras, só posições. */
+export function pageTextFromContent(content) {
+    const lines = [];
+    for (const item of content.items) {
+        if (!('str' in item) || item.str === '')
+            continue;
+        const x = Number(item.transform[4] ?? 0);
+        const y = Number(item.transform[5] ?? 0);
+        const line = lines.find((candidate) => Math.abs(candidate.y - y) < 2);
+        if (line) {
+            line.parts.push({ x, str: item.str });
+        }
+        else {
+            lines.push({ y, parts: [{ x, str: item.str }] });
+        }
+    }
+    return lines
+        .sort((a, b) => b.y - a.y)
+        .map((line) => line.parts
+        .sort((a, b) => a.x - b.x)
+        .map((part) => part.str)
+        .join(' '))
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/** `--text`: imprime o texto da faixa no stdout (ou grava em --out), páginas
+ *  separadas por "--- Página N ---". Sem --out o stdout é só o texto (pipeável)
+ *  e o resumo vai pro stderr. */
+async function scratchExtractText(parsed, fileArg, doc, range, pageCount) {
+    const chunks = [];
+    for (let n = range.from; n <= range.to; n++) {
+        const page = await doc.getPage(n);
+        const content = await page.getTextContent();
+        chunks.push(`--- Página ${n} ---\n${pageTextFromContent(content)}`);
+    }
+    const text = `${chunks.join('\n\n')}\n`;
+    const extractedPages = range.to - range.from + 1;
+    const explicitOut = stringFlag(parsed.flags, 'out');
+    if (parsed.flags.json) {
+        printJson({
+            input: fileArg,
+            output: explicitOut ? resolve(explicitOut) : null,
+            pageCount,
+            range: { from: range.from, to: range.to },
+            extractedPages,
+            text,
+        });
+        return;
+    }
+    if (explicitOut) {
+        const outPath = resolve(explicitOut);
+        mkdirSync(dirname(outPath), { recursive: true });
+        writeFileSync(outPath, text);
+        process.stdout.write(green(`Texto extraído em ${outPath}\n`) +
+            `  faixa ${range.from}-${range.to} de ${pageCount} página(s) → ${extractedPages} página(s)\n`);
+        return;
+    }
+    process.stdout.write(text);
+    process.stderr.write(dim(`scratch extract --text: faixa ${range.from}-${range.to} de ${pageCount} página(s) → ` +
+        `${extractedPages} página(s), ${text.length} chars.\n`));
+}
+const HELP = `Uso: memoring scratch <list|download|extract> [args] [--json]
+
+Rascunhos do caderno manuscrito no Google Drive (via proxy do backend — exige
+o Drive conectado PELO APP; a CLI não inicia o OAuth do Google).
+
+  list [--all]            lista os rascunhos pelo CAMINHO da biblioteca
+                          (pasta/pasta/título), com atualização e driveFileId;
+                          default: só cadernos (FREE_NOTEBOOK); --all inclui
+                          rascunhos de card (CARD_SCRATCH, prefixo
+                          "Rascunhos de cards/<noteId|título>"); ordenado por
+                          atualização, mais novo primeiro
+  download <caminho|id>   aceita o caminho completo mostrado no list (acentos,
+        [--out <dir>]     maiúsculas e espaços livres) ou o driveFileId; baixa
+        [--metadata-only] o .scratch.json (salvo em <out>/<título-slug>.scratch.json)
+                          e, se o rascunho tem PDF de fundo, o PDF junto — pelo
+                          driveFileId do próprio arquivo quando disponível, senão
+                          resolvendo o asset <hash>.pdf na pasta assets (nome
+                          local: pdf.name legível sanitizado). --metadata-only baixa
+                          só o JSON e informa os metadados do PDF, sem o binário.
+                          Caminho não encontrado ou ambíguo = erro com os candidatos
+                          — a CLI nunca escolhe por você
+  extract <arquivo.pdf>   recorta a faixa de páginas num sub-PDF (pdf-lib, sem deps nativas)
+        [--pages A-B]     "20-35" ou "20" (página única); to além do fim é limitado ao total
+        [--all]           PDF inteiro — obrigatório explicitar quando o PDF tem mais de
+                          ~30 páginas (≈2,7 mil tokens/página: estourar o contexto do
+                          agente de propósito exige confirmação)
+        [--out <alvo>]    default: <nome>-pA-B.pdf ao lado do arquivo de origem
+        [--text]          extrai o TEXTO da faixa (pdfjs-dist) no stdout, páginas
+                          separadas por "--- Página N ---" — com --out grava em arquivo.
+                          Mesma forcing function (> ~30 páginas sem --pages exige --all)
+
+Estimativa de contexto: página densa de PDF ≈ 2.700 tokens. Acima de ~60 páginas,
+SEMPRE recorte antes de gerar flashcards.`;
+export async function scratchCommand(parsed) {
+    const [sub] = parsed._;
+    switch (sub) {
+        case 'list':
+            await scratchList(parsed);
+            return;
+        case 'download':
+            await scratchDownload(parsed);
+            return;
+        case 'extract':
+            await scratchExtract(parsed);
+            return;
+        default:
+            process.stdout.write(HELP + '\n');
+            if (sub) {
+                process.exitCode = 1;
+            }
+    }
+}