@memoring/cli 0.9.0 → 0.11.0

package/dist/commands/deck.js

@@ -28,6 +28,110 @@ export async function createDeck(name, parentId = null) {
         throw e;
     }
 }
+const COVER_TONES = ['gray', 'orange', 'green', 'blue', 'purple'];
+const GOAL_MAX_LENGTH = 160;
+const GOAL_DISPLAY_MAX = 30;
+/** "4,5" (vírgula decimal pt-BR) ou "—" quando sem relevância. */
+function formatRelevance(relevance) {
+    return relevance === null ? '—' : relevance.toFixed(1).replace('.', ',');
+}
+/** META da listagem/update: texto do goal, célula de ~30 chars. */
+function formatGoal(deck) {
+    let goal = (deck.goal ?? '').trim();
+    if (goal.length > GOAL_DISPLAY_MAX) {
+        goal = `${goal.slice(0, GOAL_DISPLAY_MAX - 1).trimEnd()}…`;
+    }
+    return goal === '' ? '—' : goal;
+}
+/** 45s | 12min | 1h05 — segundos inteiros; médias chegam já arredondadas. */
+function formatRunSeconds(seconds) {
+    if (seconds < 60) {
+        return `${seconds}s`;
+    }
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60) {
+        return `${minutes}min`;
+    }
+    return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, '0')}`;
+}
+/**
+ * Recorde exibido: para o pai é a MÉDIA ARITMÉTICA dos filhos com recorde (o
+ * fastestRunSeconds do DeckView é só do próprio baralho — quem tem a árvore
+ * toda calcula a média); sem filho com recorde, cai no próprio do baralho.
+ */
+function recordOf(deck, childrenByParent) {
+    const records = (childrenByParent.get(deck.id) ?? [])
+        .map((child) => child.fastestRunSeconds)
+        .filter((seconds) => seconds !== null);
+    if (records.length > 0) {
+        return Math.round(records.reduce((sum, seconds) => sum + seconds, 0) / records.length);
+    }
+    return deck.fastestRunSeconds;
+}
+function parseRelevanceFlag(raw) {
+    const normalized = raw.replace(',', '.');
+    if (!/^\d+(\.\d)?$/.test(normalized)) {
+        fail(`--relevance inválido: use 0 a 5 com no máximo 1 casa decimal (ex.: 4 ou 4,5 — veio ${JSON.stringify(raw)}).`);
+    }
+    const value = Number(normalized);
+    if (value > 5) {
+        fail(`--relevance deve estar entre 0 e 5 (veio ${raw}).`);
+    }
+    return value;
+}
+function parseGoalFlag(raw) {
+    const goal = raw.trim();
+    if (goal === '') {
+        fail('--goal vazio — para limpar a meta use --clear-goal.');
+    }
+    if (goal.length > GOAL_MAX_LENGTH) {
+        fail(`--goal excede ${GOAL_MAX_LENGTH} caracteres (veio ${goal.length}).`);
+    }
+    return goal;
+}
+function parseToneFlag(raw) {
+    const tone = raw.trim().toLowerCase();
+    if (!COVER_TONES.includes(tone)) {
+        fail(`--tone inválido: use ${COVER_TONES.join(' | ')} (veio ${JSON.stringify(raw)}).`);
+    }
+    return tone;
+}
+const METADATA_SPECS = [
+    { valueFlag: 'relevance', clearFlag: 'clear-relevance', field: 'relevance', parse: parseRelevanceFlag },
+    { valueFlag: 'goal', clearFlag: 'clear-goal', field: 'goal', parse: parseGoalFlag },
+    { valueFlag: 'tone', clearFlag: 'clear-tone', field: 'coverTone', parse: parseToneFlag },
+];
+/**
+ * Monta o body do PUT /metadata com SÓ os campos informados: flag de valor
+ * envia o valor validado, --clear-* envia null explícito (limpa), os dois
+ * juntos é erro. Ausente dos dois = campo intacto (o PUT não toca).
+ */
+function metadataBody(flags) {
+    const body = {};
+    for (const spec of METADATA_SPECS) {
+        const raw = stringFlag(flags, spec.valueFlag);
+        const clear = flags[spec.clearFlag] === true;
+        if (raw !== undefined && clear) {
+            fail(`--${spec.valueFlag} e --${spec.clearFlag} não podem ir juntos — use um ou outro.`);
+        }
+        if (raw !== undefined) {
+            body[spec.field] = spec.parse(raw);
+        }
+        else if (clear) {
+            body[spec.field] = null;
+        }
+    }
+    if (Object.keys(body).length === 0) {
+        fail('nada a atualizar — informe ao menos um campo: --relevance, --goal, --tone ou um --clear-*.');
+    }
+    return body;
+}
+function printDeckSummary(deck) {
+    process.stdout.write(green(`Baralho "${deck.name}" (#${deck.id}) atualizado.\n`));
+    process.stdout.write(`  relevância:  ${formatRelevance(deck.relevance)}\n`);
+    process.stdout.write(`  meta:        ${formatGoal(deck)}\n`);
+    process.stdout.write(`  tom de capa: ${deck.coverTone ?? '—'}\n`);
+}
 export async function deckCommand(parsed) {
     const [sub, ...rest] = parsed._;
     switch (sub) {
@@ -42,16 +146,33 @@ export async function deckCommand(parsed) {
                 return;
             }
             const nameById = new Map(decks.map((d) => [d.id, d.name]));
+            const childrenByParent = new Map();
+            for (const d of decks) {
+                if (d.parentId !== null) {
+                    const siblings = childrenByParent.get(d.parentId) ?? [];
+                    siblings.push(d);
+                    childrenByParent.set(d.parentId, siblings);
+                }
+            }
             printTable(decks.map((d) => ({
                 id: `#${d.id}`,
                 name: d.name,
                 parent: d.parentId !== null ? (nameById.get(d.parentId) ?? `#${d.parentId}`) : '—',
                 due: d.dueCount,
+                relevance: formatRelevance(d.relevance),
+                goal: formatGoal(d),
+                record: (() => {
+                    const record = recordOf(d, childrenByParent);
+                    return record === null ? '—' : formatRunSeconds(record);
+                })(),
             })), [
                 { key: 'id', label: 'ID' },
                 { key: 'name', label: 'NOME' },
                 { key: 'parent', label: 'BARALHO-PAI' },
                 { key: 'due', label: 'A REVISAR' },
+                { key: 'relevance', label: 'RELEVÂNCIA' },
+                { key: 'goal', label: 'META' },
+                { key: 'record', label: 'RECORDE' },
             ]);
             process.stdout.write(`\n${decks.length} baralho(s).\n`);
             return;
@@ -87,11 +208,42 @@ export async function deckCommand(parsed) {
             process.stdout.write(green(`Baralho "${deck.name}" criado (#${deck.id}).\n`));
             return;
         }
+        case 'update': {
+            const ref = rest.join(' ').trim();
+            if (ref === '') {
+                fail('informe o baralho: memoring deck update <id|nome> [--relevance 0-5] [--goal "txt"] ...');
+            }
+            const deck = resolveDeck(await listDecks(), ref);
+            if (!deck) {
+                fail(`baralho "${ref}" não encontrado — veja os ids/nomes com \`memoring deck list\`.`);
+            }
+            const body = metadataBody(parsed.flags);
+            let updated;
+            try {
+                updated = (await apiFetch(`/notes/decks/${deck.id}/metadata`, { method: 'PUT', body }));
+            }
+            catch (e) {
+                if (e instanceof ApiError) {
+                    fail(`o servidor rejeitou a atualização do baralho "${deck.name}" (#${deck.id}) (${e.status}): ${e.body}`);
+                }
+                throw e;
+            }
+            if (parsed.flags.json) {
+                printJson(updated);
+                return;
+            }
+            printDeckSummary(updated);
+            return;
+        }
         default:
-            process.stdout.write('Uso: memoring deck <list|create> [nome] [--parent <id>] [--json]\n' +
-                '  list            lista seus baralhos (id, nome, pai, cartões a revisar)\n' +
-                '  create <nome>   cria um baralho (idempotente: nome existente só retorna o atual)\n' +
-                '                  --parent <id|nome> cria como sub-baralho\n');
+            process.stdout.write('Uso: memoring deck <list|create|update> [id|nome] [flags]\n' +
+                '  list             lista seus baralhos (id, nome, pai, a revisar, relevância, meta, recorde)\n' +
+                '  create <nome>    cria um baralho (idempotente: nome existente só retorna o atual)\n' +
+                '                   --parent <id|nome> cria como sub-baralho\n' +
+                '  update <id|nome> define metadados do baralho\n' +
+                '                   --relevance 0-5 (1 casa) | --goal "txt" (<=160)\n' +
+                '                   --tone gray|orange|green|blue|purple\n' +
+                '                   --clear-relevance --clear-goal --clear-tone (limpa o campo) | --json\n');
             if (sub) {
                 process.exitCode = 1;
             }

package/dist/commands/stage.js

@@ -189,7 +189,11 @@ const SCHEMA_TEXT = `Contrato dos itens da caixa de revisão (POST /api/notes/re
   question      objeto — snapshot da questão      (obrigatório quando type=QUESTION)
   deckName      string — baralho de destino       (OBRIGATÓRIO — cartão não fica sem baralho:
                                                    veja \`memoring deck list\`, reutilize ou crie
-                                                   com \`memoring deck create\`; --deck = padrão do lote)
+                                                   com \`memoring deck create\`; --deck = padrão do lote.
+                                                   Espelhe a hierarquia do material: matéria = baralho
+                                                   raiz; tema da aula/capítulo = sub-baralho criado
+                                                   ANTES com \`deck create "<tema>" --parent "<matéria>"\`
+                                                   — o create-por-nome só cria baralho raiz)
   subjectName?  string — matéria (ex.: "Direito Constitucional")
   subtopicName? string — subtópico
   tags?         string[]

package/dist/main.js

@@ -9,7 +9,7 @@ import { updateCommand } from './commands/update.js';
 import { skillCommand } from './commands/skill.js';
 import { parseArgs as parse } from './commands/shared.js';
 import { newerVersionAvailable, scheduleUpdateCheck } from './update.js';
-const VERSION = '0.9.0';
+const VERSION = '0.11.0';
 const HELP = `Memoring CLI — flashcards e notas por IA, direto do terminal.
 
 Uso: memoring <comando> [subcomando] [flags]
@@ -28,8 +28,10 @@ Comandos:
   inbox discard-all             descarta todos os itens pendentes
   inbox update <id>             edita um item pendente (--file parcial e/ou flags,
                                 inclui --deck <id|nome>)
-  deck list                     seus baralhos (id, nome, pai)
-  deck create <nome>            cria um baralho (--parent <id> p/ sub-baralho)
+  deck list                     seus baralhos (id, nome, pai, a revisar, relevância, meta, recorde)
+  deck create <nome>            cria um baralho (--parent <id|nome> p/ sub-baralho)
+  deck update <id|nome>         metadados do baralho (--relevance/--goal/--tone;
+                                --clear-* limpa um campo)
   update                        atualiza a CLI para a versão mais recente (via npm)
   skill                         guia completo da CLI para agentes de IA (imprime o SKILL.md)
   version                       versão da CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memoring/cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "CLI do Memoring — envie flashcards/notas gerados por IA para a sua caixa de revisão, direto do terminal.",
   "repository": {
     "type": "git",

package/skills/memoring-cli/SKILL.md

@@ -21,8 +21,9 @@ O Memoring é um app de estudos com revisão espaçada (FSRS). A CLI `memoring`
 | `memoring stage schema [--json]` | O CONTRATO dos itens + limites por tipo + regras de qualidade — leia SEMPRE, logado, antes de gerar |
 | `memoring stage caps [--max-* N\|livre]` | limites por tipo do usuário (preferência DELE — nunca escreva sem ele pedir) |
 | `memoring stage create --file f [--replace] [--max-* N] [--deck nome]` | envia o lote (1 a 50 itens) para a caixa de revisão — **baralho OBRIGATÓRIO** (deckName por item ou `--deck` no lote; nomes novos viram baralhos); `--json` devolve `created` + `ids` |
-| `memoring deck list` | seus baralhos (id, nome, pai) — consulte ANTES de gerar |
+| `memoring deck list` | seus baralhos (id, nome, pai, a revisar, relevância, meta, recorde) — consulte ANTES de gerar |
 | `memoring deck create <nome> [--parent id]` | cria baralho (idempotente) |
+| `memoring deck update <id\|nome> [--relevance <0-5>] [--goal "<txt>"] [--tone <gray\|orange\|green\|blue\|purple>] [--clear-*]` | define metadados do baralho (relevância, meta, tom de capa; `--clear-*` limpa o campo) |
 | `memoring inbox list` | itens pendentes de revisão |
 | `memoring inbox accept <id>\|accept-all` | aceita itens (entram nas listagens e na fila FSRS) |
 | `memoring inbox discard <id>\|discard-all` | descarta item(ns) pendente(s) |
@@ -37,7 +38,7 @@ Flags globais: `--json` (saída legível por máquina), `--no-color`, `--api-bas
 1. **Entenda o pedido** — qual pasta/arquivo/material vira flashcards/notas e se o usuário pediu quantidades.
 2. **Confira a sessão**: `memoring auth status --json`. Sem `authenticated: true`, PARE e peça o login (ver Pré-requisitos).
 3. **Leia o contrato, os limites e as regras**: `memoring stage schema --json` (logado). Além do contrato, a saída traz: `userCaps` — os limites por tipo DO USUÁRIO (`-1` = à vontade, `0` = não gerar o tipo, `N` = teto), respeite-os SEMPRE; `qualityRules` — as regras de qualidade INTEGRAIS (as mesmas que o app envia à LLM), aplique-as em TODOS os itens; `customInstructions` — instruções adicionais do usuário (quando não-nulas), também sempre aplicadas. Tudo isso vale mesmo sem pedido explícito no chat.
-4. **Defina o baralho** — cartão NÃO fica sem baralho. Rode `memoring deck list`, escolha o baralho adequado ao material e reutilize o nome; se não existir, crie com `memoring deck create "<nome>"` (ou deixe o próprio `stage create` criar pelo nome). Todo item do lote deve levar `deckName` — ou use `--deck "<nome>"` no create como padrão do lote. Lote sem baralho é REJEITADO pela validação local.
+4. **Defina o baralho** — cartão NÃO fica sem baralho. Rode `memoring deck list`, escolha o baralho adequado ao material e reutilize o nome; se não existir, crie com `memoring deck create "<nome>"` (ou deixe o próprio `stage create` criar pelo nome). **Espelhe a hierarquia do material:** a matéria vira baralho raiz; o tema da aula/capítulo vira sub-baralho criado ANTES com `memoring deck create "<tema>" --parent "<matéria>"` — o create-por-nome do `stage create` só cria baralho raiz. Todo item do lote deve levar `deckName` — ou use `--deck "<nome>"` no create como padrão do lote. Lote sem baralho é REJEITADO pela validação local.
 5. **Leia os materiais** e gere os itens no contrato, num arquivo JSON (array ou `{ "items": [...] }`).
 6. **Envie**: `memoring stage create --file <arquivo> --json`. Se o lote for rejeitado por limite de tipo, ajuste o LOTE — não relaxe o limite do usuário.
 7. **Guarde os `ids` retornados** pelo create: enquanto os itens estiverem PENDING_REVIEW você pode corrigi-los com `memoring inbox update <id>` — sem precisar descartar e reenviar.
@@ -47,7 +48,7 @@ Flags globais: `--json` (saída legível por máquina), `--no-color`, `--api-bas
 
 - `type`: `NOTE` (nota, exige `content` markdown; `NORMAL` legado é aceito e mapeado para `NOTE`), `FLASHCARD` ou `ONE_SHOT` (exigem `front` + `back`) ou `QUESTION` (exige `question` — ver abaixo).
 - `title` sempre obrigatório; lote de 1 a 50 itens, all-or-nothing — qualquer item inválido rejeita o lote inteiro.
-- `deckName` **OBRIGATÓRIO** (ou `--deck` no create como padrão do lote): cartão não fica sem baralho. Use o nome de um baralho de `memoring deck list`; nome inexistente é criado no envio.
+- `deckName` **OBRIGATÓRIO** (ou `--deck` no create como padrão do lote): cartão não fica sem baralho. Use o nome de um baralho de `memoring deck list`; nome inexistente é criado no envio. Espelhe a hierarquia do material: matéria = baralho raiz; tema da aula/capítulo = sub-baralho criado ANTES com `deck create "<tema>" --parent "<matéria>"` (o `stage create` só cria raiz pelo nome).
 - `ONE_SHOT` = pergunta de resposta única (UMA palavra ou termo curto, texto puro). Ative o tipo sempre que o cobrável for recall de termo puro — nome de princípio/instituto, termo em latim, sigla, número de lei/artigo, data, prazo. Resposta cabe num termo → `ONE_SHOT`; exige frase ou explicação → `FLASHCARD`.
 - `QUESTION` = questão objetiva para verificação: `question.kind` (`MULTIPLA_ESCOLHA` | `CERTO_ERRADO`), `question.statementHtml` (enunciado), `question.correctAlternative` (gabarito, int 1-based; em CERTO_ERRADO, 1 = Certo, 2 = Errado), `question.alternatives` (2 a 5 textos — só em MULTIPLA_ESCOLHA), `question.commentHtml` (explicação do gabarito). **Se o material contiver questões prontas (provas, simulados, listas C/E), APROVEITE-AS como QUESTION** preservando enunciado e gabarito — não as achate em flashcards.
 - Preencha `source` com a origem real do material (nome do arquivo/pasta) — não use o default quando souber a origem.