@memoring/cli 0.11.0 → 0.12.0

package/README.md

@@ -56,7 +56,7 @@ Os itens enviados nascem **PENDING_REVIEW** — nada entra nas suas listagens ne
 | `memoring auth` | login / logout / status |
 | `memoring stage` | schema (o contrato + seus limites por tipo + as regras de qualidade e suas instruções custom — tudo que o agente deve seguir) / caps (mostra/grava os limites — valem para o app e para os agentes) / create (envia o lote, `--file` ou stdin, `--replace` esvazia a caixa antes; `--max-*` vence a preferência por lote) |
 | `memoring inbox` | list / accept `<id>` / accept-all / discard `<id>` / discard-all / update `<id>` (edita item PENDENTE — merge do `--file` parcial e/ou flags `--title --front --back --tags a,b --deck nome ...`) |
-| `memoring deck` | list (seus baralhos) / create `<nome>` (idempotente; `--parent` p/ sub-baralho) |
+| `memoring deck` | list (seus baralhos, com status ACTIVE/PENDING) / create `<nome>` (idempotente; `--parent` p/ sub-baralho; `--pending` p/ estrutura de importação — o baralho só aparece no app quando o primeiro item é aceito) |
 | `memoring update` | atualiza a CLI para a última versão (via npm) |
 | `memoring skill` | imprime o guia completo da CLI para agentes de IA (o SKILL.md empacotado) |
 | `memoring version` | versão da CLI |
@@ -102,6 +102,8 @@ Cada item do lote (1 a 50, all-or-nothing):
 
 Este pacote inclui uma skill em `skills/memoring-cli/SKILL.md` com o fluxo completo (auth → schema → gerar → stage → avisar o usuário). O jeito mais fácil de um agente aprender a CLI de cabo a rabo é rodar **`memoring skill`** — o comando imprime o guia completo empacotado. Ou simplesmente peça "use a cli do memoring" — os comandos são auto-descritivos (`--help` em todos).
 
+> **Aceite é decisão do usuário.** O fluxo do agente termina no `stage create` + aviso para revisar em [memoring.com.br/cards/inbox](https://memoring.com.br/cards/inbox). `memoring inbox accept <id>` / `accept-all` existem para **você** rodar — um agente só os executa quando você pedir explicitamente.
+
 ## Dev (backend local)
 
 ```

package/dist/commands/deck.js

@@ -1,7 +1,11 @@
 import { apiFetch, ApiError } from '../api.js';
-import { fail, green, printJson, printTable, stringFlag } from './shared.js';
+import { fail, green, dim, printJson, printTable, stringFlag } from './shared.js';
+/**
+ * Lista ACTIVE + PENDING (?includePending=true): create/update/stage reutilizam
+ * baralhos pendentes por nome de forma idempotente e a listagem mostra o estado.
+ */
 export async function listDecks() {
-    return (await apiFetch('/notes/decks'));
+    return (await apiFetch('/notes/decks?includePending=true'));
 }
 /**
  * Resolve uma referência de baralho ("123" por id ou nome exato, case-insensitive)
@@ -16,10 +20,11 @@ export function resolveDeck(decks, ref) {
     const norm = ref.trim().toLowerCase();
     return decks.find((d) => d.name.trim().toLowerCase() === norm) ?? null;
 }
-/** Cria o baralho (parentId null = baralho raiz/matéria). */
-export async function createDeck(name, parentId = null) {
+/** Cria o baralho (parentId null = baralho raiz/matéria). O boolean `pending` é
+ * sempre explícito no body — sem ele, a chamada seria ambígua quanto ao status. */
+export async function createDeck(name, parentId, pending) {
     try {
-        return (await apiFetch('/notes/decks', { method: 'POST', body: { name, parentId } }));
+        return (await apiFetch('/notes/decks', { method: 'POST', body: { name, parentId, pending } }));
     }
     catch (e) {
         if (e instanceof ApiError) {
@@ -157,6 +162,7 @@ export async function deckCommand(parsed) {
             printTable(decks.map((d) => ({
                 id: `#${d.id}`,
                 name: d.name,
+                status: d.status,
                 parent: d.parentId !== null ? (nameById.get(d.parentId) ?? `#${d.parentId}`) : '—',
                 due: d.dueCount,
                 relevance: formatRelevance(d.relevance),
@@ -168,6 +174,7 @@ export async function deckCommand(parsed) {
             })), [
                 { key: 'id', label: 'ID' },
                 { key: 'name', label: 'NOME' },
+                { key: 'status', label: 'STATUS' },
                 { key: 'parent', label: 'BARALHO-PAI' },
                 { key: 'due', label: 'A REVISAR' },
                 { key: 'relevance', label: 'RELEVÂNCIA' },
@@ -180,7 +187,7 @@ export async function deckCommand(parsed) {
         case 'create': {
             const name = rest.join(' ').trim();
             if (name === '') {
-                fail('informe o nome: memoring deck create "Direito Tributário" [--parent <id>].');
+                fail('informe o nome: memoring deck create "Direito Tributário" [--parent <id>] [--pending].');
             }
             let parentId = null;
             const parentRef = stringFlag(parsed.flags, 'parent');
@@ -200,12 +207,15 @@ export async function deckCommand(parsed) {
                 process.stdout.write(`Baralho "${existing.name}" já existe (#${existing.id}).\n`);
                 return;
             }
-            const deck = await createDeck(name, parentId);
+            const deck = await createDeck(name, parentId, parsed.flags.pending === true);
             if (parsed.flags.json) {
                 printJson({ deck, alreadyExisted: false });
                 return;
             }
-            process.stdout.write(green(`Baralho "${deck.name}" criado (#${deck.id}).\n`));
+            process.stdout.write(green(`Baralho "${deck.name}" criado (#${deck.id}).\n`) +
+                (deck.status === 'PENDING'
+                    ? dim('  PENDING — oculto no app até o primeiro item aceite (o aceite ativa o baralho e os ancestrais pendentes).\n')
+                    : ''));
             return;
         }
         case 'update': {
@@ -237,9 +247,11 @@ export async function deckCommand(parsed) {
         }
         default:
             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' +
+                '  list             lista seus baralhos (id, nome, status, 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' +
+                '                   --pending cria PENDING (estrutura de importação: oculto no app\n' +
+                '                   até o primeiro item aceite, que ativa o baralho e os ancestrais)\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' +

package/dist/commands/stage.js

@@ -147,7 +147,7 @@ const SCHEMA_JSON = {
         subjectName: 'string? — matéria (ex.: "Direito Constitucional")',
         subtopicName: 'string? — subtópico',
         tags: 'string[]?',
-        deckName: 'string (OBRIGATÓRIO — cartão não fica sem baralho: consulte `memoring deck list`, reutilize um existente ou crie com `memoring deck create`; nome inexistente é criado no envio. A flag --deck do create vale como padrão do lote)',
+        deckName: 'string (OBRIGATÓRIO — cartão não fica sem baralho: consulte `memoring deck list`, reutilize um existente ou crie com `memoring deck create`; nome inexistente é criado no envio como PENDING — oculto no app até o 1º item aceite, que ativa o baralho e os ancestrais pendentes. A flag --deck do create vale como padrão do lote)',
         question: 'objeto? — snapshot da questão (obrigatório quando type=QUESTION; contrato em questionContract)',
         source: `string? — origem do material (default: "${DEFAULT_SOURCE}")`,
     },
@@ -189,11 +189,13 @@ 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 --pending\`; --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)
+                                                   ANTES com \`deck create "<tema>" --parent "<matéria>" --pending\`
+                                                   — o create-por-nome só cria baralho raiz. Baralhos
+                                                   PENDING ficam ocultos no app até o 1º item aceite,
+                                                   que ativa o baralho e os ancestrais pendentes)
   subjectName?  string — matéria (ex.: "Direito Constitucional")
   subtopicName? string — subtópico
   tags?         string[]
@@ -217,7 +219,8 @@ QUESTION treina verificação objetiva (aproveite questões prontas do material)
 Limites por tipo: a preferência do usuário (abaixo, quando logado) vale por padrão;
 --max-notes N | --max-flashcards N | --max-one-shots N | --max-questions N no create vencem por lote ("livre" = à vontade).`;
 const NO_DECK_HINT = 'cartão não fica sem baralho: informe deckName no item ou --deck "<nome>" no lote. ' +
-    'Veja `memoring deck list` e reutilize um existente, ou crie com `memoring deck create "<nome>"`.';
+    'Veja `memoring deck list` e reutilize um existente, ou crie com `memoring deck create "<nome>" --pending` ' +
+    '(estrutura de importação fica oculta até o primeiro aceite).';
 /** Exige baralho em TODO o lote: deckName no item ou a flag --deck como padrão. */
 function enforceDeck(items, flags) {
     const batchDeck = stringFlag(flags, 'deck');
@@ -228,8 +231,10 @@ function enforceDeck(items, flags) {
 }
 /**
  * Resolve os baralhos do lote ANTES do POST: referências existentes são reutilizadas
- * (id numérico ou nome exato case-insensitive) e nomes novos viram baralhos criados
- * na hora — o agente nunca precisa sair do fluxo para criar estrutura.
+ * (id numérico ou nome exato case-insensitive, ativos E pendentes) e nomes novos viram
+ * baralhos PENDING criados na hora — invisíveis no app até o primeiro item aceite, que
+ * ativa o baralho e os ancestrais pendentes. O agente nunca precisa sair do fluxo
+ * para criar estrutura.
  */
 async function resolveBatchDecks(items, flags) {
     const batchDeck = stringFlag(flags, 'deck')?.trim();
@@ -256,7 +261,7 @@ async function resolveBatchDecks(items, flags) {
         if (Number.isInteger(Number(ref)) && Number(ref) > 0) {
             fail(`baralho #${ref} não existe — ${NO_DECK_HINT}`);
         }
-        const deck = await createDeck(ref);
+        const deck = await createDeck(ref, null, true);
         decks.push(deck);
         idByRef.set(ref, deck.id);
         createdNames.push(ref);
@@ -540,7 +545,7 @@ export async function stageCommand(parsed) {
                 }
             }
             if (batchDecks.createdNames.length > 0 && !parsed.flags.json) {
-                process.stdout.write(dim(`Baralho(s) criado(s): ${batchDecks.createdNames.join(', ')}.\n`));
+                process.stdout.write(dim(`Baralho(s) criado(s) como PENDING (ocultos até o 1º aceite): ${batchDecks.createdNames.join(', ')}.\n`));
             }
             let created;
             try {
@@ -601,7 +606,8 @@ export async function stageCommand(parsed) {
                 '  create   envia o lote para a caixa de revisão (arquivo ou stdin)\n' +
                 '           tipos: NOTE | FLASHCARD | ONE_SHOT | QUESTION\n' +
                 '           baralho OBRIGATÓRIO: deckName por item ou --deck "<nome|id>" no lote\n' +
-                '           (nomes inexistentes são criados; veja `memoring deck list`)\n' +
+                '           (nomes inexistentes são criados como PENDING — ocultos no app até o\n' +
+                '           primeiro aceite; veja `memoring deck list`)\n' +
                 '           --replace esvazia a caixa antes de enviar\n' +
                 '           --max-notes N | --max-flashcards N | --max-one-shots N | --max-questions N\n' +
                 '           vencem a preferência gravada por lote (validação local)\n');

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.11.0';
+const VERSION = '0.12.0';
 const HELP = `Memoring CLI — flashcards e notas por IA, direto do terminal.
 
 Uso: memoring <comando> [subcomando] [flags]
@@ -28,8 +28,8 @@ 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, a revisar, relevância, meta, recorde)
-  deck create <nome>            cria um baralho (--parent <id|nome> p/ sub-baralho)
+  deck list                     seus baralhos (id, nome, status, pai, a revisar, relevância, meta, recorde)
+  deck create <nome>            cria um baralho (--parent <id|nome> p/ sub-baralho; --pending p/ importação)
   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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memoring/cli",
-  "version": "0.11.0",
+  "version": "0.12.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,11 +21,11 @@ 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, a revisar, relevância, meta, recorde) — consulte ANTES de gerar |
-| `memoring deck create <nome> [--parent id]` | cria baralho (idempotente) |
+| `memoring deck list` | seus baralhos (id, nome, status, pai, a revisar, relevância, meta, recorde) — consulte ANTES de gerar |
+| `memoring deck create <nome> [--parent id] [--pending]` | cria baralho (idempotente); `--pending` deixa oculto até o primeiro item aceite |
 | `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 accept <id>\|accept-all` | aceita itens (entram nas listagens e na fila FSRS) — **decisão do usuário: só rode se ELE pedir explicitamente** |
 | `memoring inbox discard <id>\|discard-all` | descarta item(ns) pendente(s) |
 | `memoring inbox update <id> [--file parcial.json] [--title ...] [--front ...] [--back ...] [--tags a,b] ...` | edita um item AINDA PENDENTE (merge com o estado atual) |
 | `memoring skill` | imprime este guia |
@@ -38,17 +38,17 @@ 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). **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.
+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 e a estrutura for destinada à importação, crie com `memoring deck create "<nome>" --pending` (ou deixe o próprio `stage create` criar pelo nome — nesse caso o baralho também nasce **PENDING**). **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>" --pending` — o create-por-nome do `stage create` só cria baralho raiz. Use `--pending` na estrutura criada para importação: baralhos PENDING ficam ocultos no app (árvore, filtros, fila, estatísticas) até o **primeiro item aceite** — o aceite ativa o baralho E os ancestrais pendentes de uma vez; descartar não ativa. 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.
-8. **Avise o usuário**: quantos itens foram para a caixa de revisão e onde aceitar — no app em `/cards/inbox` ou `memoring inbox list` / `memoring inbox accept-all`.
+8. **Avise o usuário e PARE**: informe quantos itens foram para a caixa de revisão, os `ids` e onde ele revisa — no app em `/cards/inbox` (ou `memoring inbox list` para ver o estado). O fluxo termina AQUI: aceitar (`memoring inbox accept <id>` / `memoring inbox accept-all`) é decisão do usuário e só acontece quando ELE pedir explicitamente — aponte o caminho, não execute.
 
 ## O contrato (a fonte da verdade é `stage schema`)
 
 - `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. 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).
+- `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 como **PENDING** (oculto no app até o 1º item aceite). 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>" --pending` (o `stage create` só cria raiz pelo nome). O primeiro item aceito ativa o baralho e os ancestrais pendentes.
 - `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.
@@ -69,6 +69,7 @@ Cartões atômicos: UMA ideia por cartão — se um conceito tem 3 partes cobrá
 ## Armadilhas
 
 - **Nunca** use `--replace` ou `inbox discard-all` sem o usuário pedir explicitamente — eles apagam os itens pendentes existentes da caixa.
+- **Nunca** aceite itens em nome do usuário: `memoring inbox accept-all` e `memoring inbox accept <id>` só podem ser rodados quando o usuário pedir EXPLICITAMENTE a aceitação. Conferir o lote tecnicamente (JSON válido, gabarito correto, limites respeitados) é revisão SUA, não revisão do usuário — não conta como pedido de aceite. Sem pedido explícito, o fluxo termina no aviso para ele revisar em `/cards/inbox`.
 - Se aparecer um aviso de versão nova no stderr, ignore e siga o fluxo — **não** rode `memoring update` por conta própria; atualizar a CLI é decisão do usuário.
 - **Não** altere os limites do usuário (`stage caps`) por conta própria — é preferência dele, compartilhada com o app.
 - Se `stage create` falhar com erro de validação do servidor, corrija os itens indicados e reenvie — não relaxe o contrato.