@memoring/cli 0.2.0 → 0.4.0

package/README.md

@@ -10,6 +10,16 @@ A CLI não tem LLM própria: quem lê o material e gera os flashcards é o seu a
 npm install -g @memoring/cli
 ```
 
+## Atualização
+
+A CLI verifica em background (no máximo 1x a cada 24h) se há versão nova no npm e avisa no stderr — nunca bloqueia o comando nem polui a saída `--json`. Para atualizar:
+
+```
+memoring update    # equivale a npm i -g @memoring/cli@latest
+```
+
+`MEMORING_NO_UPDATE_CHECK=1` desativa a verificação.
+
 ## Quickstart
 
 Autentique (abre o browser — sem senha no terminal):
@@ -44,8 +54,9 @@ Os itens enviados nascem **PENDING_REVIEW** — nada entra nas suas listagens ne
 | Command | Purpose |
 | --- | --- |
 | `memoring auth` | login / logout / status |
-| `memoring stage` | schema (o contrato) / create (envia o lote, `--file` ou stdin, `--replace` esvazia a caixa antes, `--max-notes\|--max-flashcards\|--max-one-shots` limitam cada tipo) |
+| `memoring stage` | schema (o contrato + seus limites por tipo) / 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>` |
+| `memoring update` | atualiza a CLI para a última versão (via npm) |
 | `memoring version` | versão da CLI |
 
 ## Flags
@@ -81,6 +92,7 @@ Cada item do lote (1 a 50, all-or-nothing):
 
 - `type`: `NOTE` (nota, exige `content` em markdown; `NORMAL` legado é aceito e mapeado para `NOTE`), `FLASHCARD` ou `ONE_SHOT` (exigem `front` + `back`).
 - `source`: origem do material — default `"Importação assistida (CLI)"`.
+- Limites por tipo: `memoring stage caps` mostra/grava sua preferência (0 = não gerar o tipo) — o `stage schema` a expõe ao agente e o `create` a impõe; flags `--max-*` no `create` vencem por lote.
 
 ## Para agentes de IA
 
@@ -95,5 +107,6 @@ memoring auth login
 ```
 
 Variáveis: `MEMORING_API_BASE`, `MEMORING_KEYCLOAK_URL`, `MEMORING_KC_REALM`, `MEMORING_KC_CLIENT`, `MEMORING_CONFIG_HOME` (isola o config.json).
+Override de ambiente vale por sessão: o `auth login` não o grava no config.json — exporte as variáveis em cada shell (ou use `memoring --api-base ...` por comando).
 
 Build a partir do repo: `cd cli && npm install && npm run build && node dist/main.js --help`.

package/dist/api.js

@@ -1,5 +1,6 @@
 import { getAccessToken } from './auth.js';
 import { loadConfig } from './config.js';
+const API_TIMEOUT_MS = 30_000;
 export class ApiError extends Error {
     status;
     body;
@@ -9,6 +10,9 @@ export class ApiError extends Error {
         this.body = body;
     }
 }
+/** Resposta reutilizada do dedupe server-side (X-Client-Request-Deduped) — a escrita já foi processada antes. */
+export class ApiDedupedError extends Error {
+}
 /** fetch autenticado contra a API do Memoring; em 401, força refresh e tenta uma vez mais. */
 export async function apiFetch(path, options = {}) {
     const cfg = loadConfig();
@@ -18,13 +22,18 @@ export async function apiFetch(path, options = {}) {
         headers: {
             Authorization: `Bearer ${token}`,
             ...(options.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+            ...(options.requestId ? { 'X-Client-Request-Id': options.requestId } : {}),
         },
         body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+        signal: AbortSignal.timeout(API_TIMEOUT_MS),
     });
     let res = await doFetch(await getAccessToken());
     if (res.status === 401) {
         res = await doFetch(await getAccessToken({ forceRefresh: true }));
     }
+    if (res.headers.get('X-Client-Request-Deduped') === 'true') {
+        throw new ApiDedupedError();
+    }
     if (res.status === 204) {
         return null;
     }

package/dist/auth.js

@@ -1,8 +1,12 @@
+import { closeSync, openSync, statSync } from 'node:fs';
 import { exec } from 'node:child_process';
-import { loadConfig, saveSession, saveTokens } from './config.js';
+import { loadConfig, ensureConfigDir, refreshLockPath, releaseRefreshLock, saveSession, saveTokens, storedEndpoints } from './config.js';
 import { bold, cyan, dim, fail } from './output.js';
 const EXPIRY_MARGIN_MS = 30_000;
 const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+const FETCH_TIMEOUT_MS = 15_000;
+const REFRESH_LOCK_WAIT_MS = 20_000;
+const REFRESH_LOCK_STALE_MS = 60_000;
 function realmBase(cfg) {
     return `${cfg.keycloakUrl}/realms/${cfg.realm}`;
 }
@@ -43,6 +47,7 @@ async function requestToken(cfg, params) {
         method: 'POST',
         headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
         body: new URLSearchParams({ client_id: cfg.clientId, ...params }),
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
     });
 }
 /** Device Authorization Grant (RFC 8628): mostra o código, abre o browser e faz poll até aprovar. */
@@ -52,6 +57,7 @@ export async function deviceLogin(options = {}) {
         method: 'POST',
         headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
         body: new URLSearchParams({ client_id: cfg.clientId, scope: 'openid profile email' }),
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
     });
     if (!res.ok) {
         fail(`não foi possível iniciar o login (${res.status}): ${await res.text()}`);
@@ -74,16 +80,18 @@ export async function deviceLogin(options = {}) {
             fail('o código expirou — rode `memoring auth login` de novo.');
         }
         await sleep(intervalMs);
-        const poll = await requestToken(cfg, { grant_type: DEVICE_GRANT, device_code: device.device_code });
+        let poll;
+        try {
+            poll = await requestToken(cfg, { grant_type: DEVICE_GRANT, device_code: device.device_code });
+        }
+        catch {
+            // erro transitório de rede — o poll continua (o código já pode ter sido aprovado)
+            continue;
+        }
         if (poll.ok) {
             const tokens = (await poll.json());
             const email = decodeJwtEmail(tokens.access_token);
-            saveSession({
-                keycloakUrl: cfg.keycloakUrl,
-                realm: cfg.realm,
-                clientId: cfg.clientId,
-                apiBase: cfg.apiBase,
-            }, {
+            saveSession(storedEndpoints(), {
                 accessToken: tokens.access_token,
                 refreshToken: tokens.refresh_token,
                 accessTokenExpiresAt: Date.now() + tokens.expires_in * 1000,
@@ -98,6 +106,8 @@ export async function deviceLogin(options = {}) {
             case 'slow_down':
                 intervalMs += 5000;
                 continue;
+            case 'temporarily_unavailable':
+                continue;
             case 'access_denied':
                 fail('login negado no navegador.');
                 break;
@@ -105,24 +115,56 @@ export async function deviceLogin(options = {}) {
                 fail('o código expirou — rode `memoring auth login` de novo.');
                 break;
             default:
+                if (poll.status === 429 || poll.status >= 500) {
+                    // erro transitório do servidor — backoff e segue o poll
+                    intervalMs = Math.min(intervalMs + 5000, 60_000);
+                    continue;
+                }
                 fail(`falha no login: ${err.error_description ?? err.error ?? `HTTP ${poll.status}`}`);
         }
     }
 }
-/** Access token válido — renova via refresh token quando perto de expirar. */
-export async function getAccessToken(options = {}) {
-    const cfg = loadConfig();
-    if (!options.forceRefresh &&
-        cfg.accessToken &&
-        cfg.accessTokenExpiresAt &&
-        cfg.accessTokenExpiresAt > Date.now() + EXPIRY_MARGIN_MS) {
-        return cfg.accessToken;
+function hasValidAccessToken(cfg) {
+    return Boolean(cfg.accessToken && cfg.accessTokenExpiresAt && cfg.accessTokenExpiresAt > Date.now() + EXPIRY_MARGIN_MS);
+}
+function tryAcquireRefreshLock() {
+    ensureConfigDir();
+    try {
+        const fd = openSync(refreshLockPath(), 'wx');
+        closeSync(fd);
+        return true;
     }
-    if (!cfg.refreshToken) {
-        fail('você não está autenticado. Rode `memoring auth login`.');
+    catch (e) {
+        if (e.code !== 'EEXIST') {
+            return false;
+        }
+    }
+    try {
+        // lock de processo morto — libera e tenta de novo
+        if (Date.now() - statSync(refreshLockPath()).mtimeMs > REFRESH_LOCK_STALE_MS) {
+            releaseRefreshLock();
+            const fd = openSync(refreshLockPath(), 'wx');
+            closeSync(fd);
+            return true;
+        }
+    }
+    catch {
+        // lock removido por outro processo entre o stat e a liberação
     }
+    return false;
+}
+async function doRefresh(cfg) {
     const res = await requestToken(cfg, { grant_type: 'refresh_token', refresh_token: cfg.refreshToken });
     if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        if (err.error === 'invalid_grant') {
+            // O realm revoga o refresh token no primeiro uso: se outro processo renovou
+            // antes, o config.json já tem os tokens novos — re-leio em vez de deslogar.
+            const fresh = loadConfig();
+            if (fresh.refreshToken && fresh.refreshToken !== cfg.refreshToken && hasValidAccessToken(fresh)) {
+                return fresh.accessToken;
+            }
+        }
         fail('sessão expirada. Rode `memoring auth login`.');
     }
     const tokens = (await res.json());
@@ -134,6 +176,43 @@ export async function getAccessToken(options = {}) {
     });
     return tokens.access_token;
 }
+/** Access token válido — renova via refresh token quando perto de expirar. */
+export async function getAccessToken(options = {}) {
+    const cfg = loadConfig();
+    if (!options.forceRefresh && hasValidAccessToken(cfg)) {
+        return cfg.accessToken;
+    }
+    if (!cfg.refreshToken) {
+        fail('você não está autenticado. Rode `memoring auth login`.');
+    }
+    // Single-flight entre processos: o primeiro a renovar revoga o refresh token
+    // antigo (revokeRefreshToken do realm), então um segundo refresh paralelo daria
+    // invalid_grant espúrio. Quem chega depois espera o lock e re-le o config.json;
+    // um lock velho (processo morto) é reapado pelo próprio tryAcquire.
+    const deadline = Date.now() + REFRESH_LOCK_WAIT_MS;
+    for (;;) {
+        if (tryAcquireRefreshLock()) {
+            try {
+                const fresh = loadConfig();
+                if (!options.forceRefresh && hasValidAccessToken(fresh)) {
+                    return fresh.accessToken;
+                }
+                return await doRefresh(fresh);
+            }
+            finally {
+                releaseRefreshLock();
+            }
+        }
+        await sleep(500);
+        const fresh = loadConfig();
+        if (hasValidAccessToken(fresh)) {
+            return fresh.accessToken;
+        }
+        if (Date.now() >= deadline) {
+            fail('sessão expirada. Rode `memoring auth login`.');
+        }
+    }
+}
 /** Logout no Keycloak (melhor esforço) — revoga o refresh token. */
 export async function serverLogout() {
     const cfg = loadConfig();
@@ -145,6 +224,7 @@ export async function serverLogout() {
             method: 'POST',
             headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
             body: new URLSearchParams({ client_id: cfg.clientId, refresh_token: cfg.refreshToken }),
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
         });
     }
     catch {

package/dist/commands/inbox.js

@@ -40,7 +40,7 @@ export async function inboxCommand(parsed) {
                     process.stdout.write(green(`Item #${note.id} [${note.type}] "${note.title}" aceito — entrou nas listagens e na fila de revisão.\n`));
                 }
                 else {
-                    await apiFetch(`/notes/${id}`, { method: 'DELETE' });
+                    await apiFetch(`/notes/review-inbox/${id}`, { method: 'DELETE' });
                     if (parsed.flags.json) {
                         printJson({ discarded: id });
                         return;
@@ -50,7 +50,10 @@ export async function inboxCommand(parsed) {
             }
             catch (e) {
                 if (e instanceof ApiError && e.status === 404) {
-                    fail(`item #${id} não encontrado — confira \`memoring inbox list\`.`);
+                    if (sub === 'accept') {
+                        fail(`item #${id} não encontrado — confira \`memoring inbox list\`.`);
+                    }
+                    fail(`item #${id} não encontrado ou já aceito — descarte só vale para itens pendentes (veja \`memoring inbox list\`).`);
                 }
                 throw e;
             }

package/dist/commands/stage.js

@@ -1,12 +1,30 @@
+import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { apiFetch, ApiError } from '../api.js';
-import { dim, fail, green, printJson, stringFlag } from './shared.js';
+import { apiFetch, ApiDedupedError, ApiError } from '../api.js';
+import { hasSession } from '../config.js';
+import { dim, fail, green, printJson, stringFlag, yellow } from './shared.js';
 const TYPES = ['NOTE', 'FLASHCARD', 'ONE_SHOT'];
 // Retrocompat: itens.json antigos com "type": "NORMAL" são normalizados para "NOTE".
 const LEGACY_TYPE_ALIASES = { NORMAL: 'NOTE' };
 const MAX_ITEMS = 50;
 const DEFAULT_SOURCE = 'Importação assistida (CLI)';
-/** Flags --max-<tipo> do `stage create`: teto por tipo no lote (validação local). */
+/**
+ * GET /notes/import/caps, fail-open: sem sessão ou sem rede devolve null (o schema
+ * continua útil deslogado e o create só perde a validação extra). Só chama a API
+ * quando HÁ sessão — o getAccessToken encerra o processo se não houver refresh token.
+ */
+async function fetchStoredCaps() {
+    if (!hasSession()) {
+        return null;
+    }
+    try {
+        return (await apiFetch('/notes/import/caps'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Flags --max-<tipo>: no `stage create` limitam o lote; no `stage caps` gravam a preferência. */
 const MAX_FLAG_BY_TYPE = {
     NOTE: 'max-notes',
     FLASHCARD: 'max-flashcards',
@@ -17,27 +35,44 @@ const TYPE_LABEL = {
     FLASHCARD: 'flashcards',
     ONE_SHOT: '1-shots',
 };
-function enforceTypeCaps(items, flags) {
-    const caps = Object.entries(MAX_FLAG_BY_TYPE)
-        .map(([type, flag]) => {
+/** Campo do ImportCaps ↔ flag (o `stage caps` também aceita --max-questions, usado pelo app). */
+const CAPS_FLAG_BY_FIELD = {
+    maxNotes: 'max-notes',
+    maxFlashcards: 'max-flashcards',
+    maxOneShots: 'max-one-shots',
+    maxQuestions: 'max-questions',
+};
+/**
+ * Teto por tipo no lote (validação local): a flag --max-<tipo> vence; sem flag, vale a
+ * preferência gravada do usuário (`memoring stage caps` / app). Tipo sem flag nem
+ * preferência fica livre.
+ */
+function enforceTypeCaps(items, flags, stored) {
+    const storedByType = stored
+        ? { NOTE: stored.maxNotes, FLASHCARD: stored.maxFlashcards, ONE_SHOT: stored.maxOneShots }
+        : {};
+    for (const [type, flag] of Object.entries(MAX_FLAG_BY_TYPE)) {
         const raw = stringFlag(flags, flag);
-        if (raw === undefined) {
-            return null;
+        let max;
+        let source;
+        if (raw !== undefined) {
+            const parsed = Number(raw);
+            if (!Number.isInteger(parsed) || parsed < 0) {
+                fail(`--${flag} inválido: use um inteiro >= 0 (veio ${JSON.stringify(raw)}).`);
+            }
+            max = parsed;
+            source = `--${flag}`;
         }
-        const max = Number(raw);
-        if (!Number.isInteger(max) || max < 0) {
-            fail(`--${flag} inválido: use um inteiro >= 0 (veio ${JSON.stringify(raw)}).`);
+        else if (storedByType[type] !== undefined) {
+            max = storedByType[type];
+            source = 'sua preferência (`memoring stage caps`)';
         }
-        return { type, flag, max };
-    })
-        .filter((cap) => cap !== null);
-    if (caps.length === 0) {
-        return;
-    }
-    for (const cap of caps) {
-        const count = items.filter((item) => item.type === cap.type).length;
-        if (count > cap.max) {
-            fail(`lote tem ${count} ${TYPE_LABEL[cap.type]} e --${cap.flag}=${cap.max}: ajuste o lote ou o limite. ` +
+        else {
+            continue;
+        }
+        const count = items.filter((item) => item.type === type).length;
+        if (count > max) {
+            fail(`lote tem ${count} ${TYPE_LABEL[type]} e o limite é ${max} (${source}). Ajuste o lote ou o limite. ` +
                 'Se um agente gerou este lote, peça a ele para respeitar os limites por tipo.');
         }
     }
@@ -66,7 +101,7 @@ const SCHEMA_JSON = {
             source: 'Apostila constitucional.pdf',
         },
     ],
-    typeCaps: 'flags opcionais do stage create: --max-notes N | --max-flashcards N | --max-one-shots N — o lote é rejeitado se algum tipo exceder o limite.',
+    typeCaps: 'preferência por usuário (`memoring stage caps`, vale para app e CLI) — o `stage schema` mostra os limites ao agente; flags do `stage create` (--max-notes N | --max-flashcards N | --max-one-shots N) vencem a preferência por lote.',
 };
 const SCHEMA_TEXT = `Contrato dos itens da caixa de revisão (POST /api/notes/review-inbox):
 
@@ -82,7 +117,8 @@ const SCHEMA_TEXT = `Contrato dos itens da caixa de revisão (POST /api/notes/re
 Lote: 1 a ${MAX_ITEMS} itens, all-or-nothing — qualquer item inválido rejeita o lote inteiro.
 Os itens nascem PENDING_REVIEW: o usuário aceita, edita ou recusa em /cards/inbox.
 Dica: FLASHCARD entra na fila de revisão espaçada (FSRS); ONE_SHOT é pergunta de resposta única.
-Limites por tipo: --max-notes N | --max-flashcards N | --max-one-shots N (o lote é rejeitado se exceder).`;
+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 no create vencem por lote.`;
 async function readStdin() {
     const chunks = [];
     for await (const chunk of process.stdin) {
@@ -126,10 +162,22 @@ function validateItems(raw) {
         return { ...it, source: typeof it.source === 'string' && it.source.trim() !== '' ? it.source : DEFAULT_SOURCE };
     });
 }
+/**
+ * Idempotência do lote: UUID derivado do conteúdo bruto. Re-rodar o mesmo arquivo
+ * após uma falha ambígua (timeout pós-commit) reenvia o mesmo X-Client-Request-Id —
+ * o servidor devolve o replay deduplicado em vez de duplicar os itens.
+ */
+function batchRequestId(raw) {
+    const digest = createHash('sha256').update(raw).digest();
+    digest[6] = (digest[6] & 0x0f) | 0x80;
+    digest[8] = (digest[8] & 0x3f) | 0x80;
+    const hex = digest.subarray(0, 16).toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
 async function emptyInbox() {
     const pending = (await apiFetch('/notes/review-inbox'));
     for (const note of pending) {
-        await apiFetch(`/notes/${note.id}`, { method: 'DELETE' });
+        await apiFetch(`/notes/review-inbox/${note.id}`, { method: 'DELETE' });
     }
     return pending.length;
 }
@@ -137,11 +185,61 @@ export async function stageCommand(parsed) {
     const [sub] = parsed._;
     switch (sub) {
         case 'schema': {
+            const caps = await fetchStoredCaps();
             if (parsed.flags.json) {
-                printJson(SCHEMA_JSON);
+                printJson(caps
+                    ? {
+                        ...SCHEMA_JSON,
+                        userCaps: {
+                            maxNotes: caps.maxNotes,
+                            maxFlashcards: caps.maxFlashcards,
+                            maxOneShots: caps.maxOneShots,
+                        },
+                    }
+                    : SCHEMA_JSON);
             }
             else {
                 process.stdout.write(SCHEMA_TEXT + '\n');
+                if (caps) {
+                    process.stdout.write(`\nLimites por tipo configurados por você — o agente DEVE respeitá-los ao gerar o lote: ` +
+                        `até ${caps.maxNotes} nota(s), até ${caps.maxFlashcards} flashcard(s), até ${caps.maxOneShots} 1-shot(s).\n` +
+                        dim('(altere com `memoring stage caps`; QUESTION não é estagiável pela CLI)\n'));
+                }
+                else {
+                    process.stdout.write(dim('\n(limites por tipo indisponíveis — faça `memoring auth login` ou verifique a conexão)\n'));
+                }
+            }
+            return;
+        }
+        case 'caps': {
+            // Sem flags mostra; com --max-* grava (merge com o atual). Sessão obrigatória.
+            const current = (await apiFetch('/notes/import/caps'));
+            const updates = {};
+            for (const [field, flag] of Object.entries(CAPS_FLAG_BY_FIELD)) {
+                const raw = stringFlag(parsed.flags, flag);
+                if (raw === undefined) {
+                    continue;
+                }
+                const value = Number(raw);
+                if (!Number.isInteger(value) || value < 0 || value > 50) {
+                    fail(`--${flag} inválido: use um inteiro entre 0 e 50 (veio ${JSON.stringify(raw)}).`);
+                }
+                updates[field] = value;
+            }
+            const hasUpdates = Object.keys(updates).length > 0;
+            const effective = hasUpdates
+                ? (await apiFetch('/notes/import/caps', { method: 'PUT', body: { ...current, ...updates } }))
+                : current;
+            if (parsed.flags.json) {
+                printJson(effective);
+                return;
+            }
+            process.stdout.write((hasUpdates ? green('Limites gravados') : 'Limites por tipo') +
+                ' — valem para a importação do app e para os agentes via CLI:\n');
+            process.stdout.write(`  notas: até ${effective.maxNotes}   flashcards: até ${effective.maxFlashcards}   ` +
+                `1-shots: até ${effective.maxOneShots}   questões: até ${effective.maxQuestions}\n`);
+            if (!hasUpdates) {
+                process.stdout.write(dim('Altere com: memoring stage caps --max-flashcards 30 (0 = não gerar o tipo)\n'));
             }
             return;
         }
@@ -165,7 +263,7 @@ export async function stageCommand(parsed) {
                 fail(`JSON inválido: ${e.message}`);
             }
             const items = validateItems(parsedJson);
-            enforceTypeCaps(items, parsed.flags);
+            enforceTypeCaps(items, parsed.flags, await fetchStoredCaps());
             if (parsed.flags.replace) {
                 const removed = await emptyInbox();
                 if (!parsed.flags.json) {
@@ -174,10 +272,25 @@ export async function stageCommand(parsed) {
             }
             let created;
             try {
-                const res = (await apiFetch('/notes/review-inbox', { method: 'POST', body: { items } }));
+                const res = (await apiFetch('/notes/review-inbox', {
+                    method: 'POST',
+                    body: { items },
+                    requestId: batchRequestId(raw),
+                }));
                 created = res.created;
             }
             catch (e) {
+                if (e instanceof ApiDedupedError) {
+                    if (parsed.flags.json) {
+                        printJson({ created: [], deduplicated: true });
+                        return;
+                    }
+                    process.stdout.write(green('Este lote já foi enviado antes — nada foi duplicado.\n'));
+                    if (parsed.flags.replace) {
+                        process.stdout.write(yellow('Atenção: --replace removeu os itens pendentes antes do envio — a caixa ficou vazia. Altere o lote e reenvie.\n'));
+                    }
+                    return;
+                }
                 if (e instanceof ApiError) {
                     fail(`o servidor rejeitou o lote (${e.status}): ${e.body}`);
                 }
@@ -194,12 +307,15 @@ export async function stageCommand(parsed) {
             return;
         }
         default:
-            process.stdout.write('Uso: memoring stage <schema|create> [--file itens.json] [--replace] [--json]\n' +
+            process.stdout.write('Uso: memoring stage <schema|caps|create> [--file itens.json] [--replace] [--json]\n' +
                 '  schema   imprime o contrato JSON dos itens (para humanos e agentes)\n' +
+                '           logado, inclui seus limites por tipo — o agente deve respeitá-los\n' +
+                '  caps     mostra/grava seus limites por tipo (--max-notes N | --max-flashcards N |\n' +
+                '           --max-one-shots N | --max-questions N; 0 = não gerar o tipo)\n' +
                 '  create   envia o lote para a caixa de revisão (arquivo ou stdin)\n' +
                 '           --replace esvazia a caixa antes de enviar\n' +
                 '           --max-notes N | --max-flashcards N | --max-one-shots N\n' +
-                '           limitam a quantidade de cada tipo no lote (validação local)\n');
+                '           vencem a preferência gravada por lote (validação local)\n');
             if (sub) {
                 process.exitCode = 1;
             }

package/dist/commands/update.js

@@ -0,0 +1,35 @@
+import { spawn } from 'node:child_process';
+import { bold, dim, fail, green, yellow } from './shared.js';
+import { fetchLatestVersion, isNewerVersion, recordUpdateCheck } from '../update.js';
+const PACKAGE = '@memoring/cli';
+export async function updateCommand(current) {
+    process.stdout.write(dim('consultando o registry npm...') + '\n');
+    const latest = await fetchLatestVersion();
+    if (latest && !isNewerVersion(latest, current)) {
+        recordUpdateCheck(latest);
+        process.stdout.write(green(`o memoring já está na versão mais recente (${current}).`) + '\n');
+        return;
+    }
+    if (latest) {
+        process.stdout.write(`atualizando ${current} → ${bold(latest)}...\n`);
+    }
+    else {
+        process.stdout.write(yellow('registry indisponível — tentando atualizar via npm mesmo assim...') + '\n');
+    }
+    const code = await runNpmGlobalInstall();
+    if (code !== 0) {
+        fail(`a atualização via npm falhou (código ${code}). Tente manualmente: npm install -g ${PACKAGE}@latest`);
+    }
+    recordUpdateCheck(latest ?? undefined);
+    process.stdout.write(green('memoring atualizado — rode `memoring version` para conferir.') + '\n');
+}
+function runNpmGlobalInstall() {
+    return new Promise((resolve) => {
+        const child = spawn('npm', ['install', '-g', `${PACKAGE}@latest`], {
+            stdio: 'inherit',
+            shell: process.platform === 'win32',
+        });
+        child.on('error', () => resolve(-1));
+        child.on('close', (code) => resolve(code ?? -1));
+    });
+}

package/dist/config.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 const DEFAULTS = {
@@ -7,7 +7,7 @@ const DEFAULTS = {
     clientId: 'memoring-cli',
     apiBase: 'https://memoring.com.br/api',
 };
-function configDir() {
+export function configDir() {
     if (process.env.MEMORING_CONFIG_HOME) {
         return process.env.MEMORING_CONFIG_HOME;
     }
@@ -41,10 +41,47 @@ export function loadConfig() {
         email: stored.email,
     };
 }
+/**
+ * Endpoints para PERSISTIR: só o que veio do arquivo ou do default. Override de
+ * ambiente (MEMORING_API_BASE etc.) é efêmero por definição — gravá-lo no
+ * config.json faria comandos futuros, sem a variável, apontarem para o
+ * ambiente errado (ex.: dev).
+ */
+export function storedEndpoints() {
+    const stored = readStored();
+    return {
+        keycloakUrl: stored.keycloakUrl ?? DEFAULTS.keycloakUrl,
+        realm: stored.realm ?? DEFAULTS.realm,
+        clientId: stored.clientId ?? DEFAULTS.clientId,
+        apiBase: stored.apiBase ?? DEFAULTS.apiBase,
+    };
+}
+function writeAtomic(json) {
+    const path = configPath();
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, json, { mode: 0o600 });
+    renameSync(tmp, path);
+}
 function writeStored(patch) {
     const merged = { ...readStored(), ...patch };
     mkdirSync(configDir(), { recursive: true });
-    writeFileSync(configPath(), JSON.stringify(merged, null, 2), { mode: 0o600 });
+    writeAtomic(JSON.stringify(merged, null, 2));
+}
+/** Lockfile que serializa o refresh de token entre processos da CLI (ver auth.ts). */
+export function refreshLockPath() {
+    return join(configDir(), 'refresh.lock');
+}
+export function ensureConfigDir() {
+    mkdirSync(configDir(), { recursive: true });
+}
+/** Remove o lockfile sem erro quando ele já foi liberado por outro processo. */
+export function releaseRefreshLock() {
+    try {
+        rmSync(refreshLockPath());
+    }
+    catch {
+        // já removido por outro processo
+    }
 }
 export function saveSession(endpoints, tokens) {
     writeStored({ ...endpoints, ...tokens });
@@ -60,7 +97,7 @@ export function clearSession() {
     void accessTokenExpiresAt;
     void email;
     mkdirSync(configDir(), { recursive: true });
-    writeFileSync(configPath(), JSON.stringify(rest, null, 2), { mode: 0o600 });
+    writeAtomic(JSON.stringify(rest, null, 2));
     return existed;
 }
 export function hasSession() {

package/dist/main.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { ApiError } from './api.js';
-import { setColorEnabled } from './output.js';
+import { setColorEnabled, yellow } from './output.js';
 import { authCommand } from './commands/auth.js';
 import { inboxCommand } from './commands/inbox.js';
 import { stageCommand } from './commands/stage.js';
+import { updateCommand } from './commands/update.js';
 import { fail, parseArgs as parse } from './commands/shared.js';
-const VERSION = '0.2.0';
+import { newerVersionAvailable, scheduleUpdateCheck } from './update.js';
+const VERSION = '0.4.0';
 const HELP = `Memoring CLI — flashcards e notas por IA, direto do terminal.
 
 Uso: memoring <comando> [subcomando] [flags]
@@ -15,19 +17,25 @@ Comandos:
   stage schema                  contrato JSON dos itens da caixa de revisão
   stage create [--file f]       envia itens (arquivo ou stdin) para a caixa de revisão
        [--replace]              esvazia a caixa antes de enviar
+  stage caps [--max-* N]        seus limites por tipo (valem pro app e pros agentes)
   inbox list                    itens pendentes de revisão
   inbox accept <id>|accept-all  aceita itens (entram nas listagens e na fila FSRS)
   inbox discard <id>            descarta um item pendente
+  update                        atualiza a CLI para a versão mais recente (via npm)
   version                       versão da CLI
 
 Flags globais:
   --json        saída legível por máquina
   --no-color    desativa cores
   --api-base    sobrescreve a URL da API (default: https://memoring.com.br/api)
+  --version     imprime a versão da CLI
   --help, -h    ajuda
 
 Ambiente (dev): MEMORING_API_BASE, MEMORING_KEYCLOAK_URL, MEMORING_KC_REALM, MEMORING_KC_CLIENT
 
+Atualização: a CLI verifica em background (1x/24h) se há versão nova e avisa no stderr.
+MEMORING_NO_UPDATE_CHECK=1 desativa a verificação.
+
 Exemplos:
   memoring auth login
   memoring stage schema
@@ -45,8 +53,21 @@ async function main() {
     if (apiBase) {
         process.env.MEMORING_API_BASE = apiBase;
     }
+    if (parsed._[0] !== 'update') {
+        scheduleUpdateCheck();
+    }
+    process.on('exit', () => {
+        const latest = newerVersionAvailable(VERSION);
+        if (latest) {
+            process.stderr.write(yellow(`\nnova versão do memoring disponível: ${VERSION} → ${latest} — rode \`memoring update\` para atualizar.\n`));
+        }
+    });
     const [command, ...rest] = parsed._;
     const sub = { _: rest, flags: parsed.flags };
+    if (parsed.flags.version) {
+        process.stdout.write(`memoring-cli ${VERSION}\n`);
+        return;
+    }
     if (parsed.flags.help || !command) {
         process.stdout.write(HELP);
         return;
@@ -61,6 +82,9 @@ async function main() {
         case 'inbox':
             await inboxCommand(sub);
             return;
+        case 'update':
+            await updateCommand(VERSION);
+            return;
         case 'version':
             process.stdout.write(`memoring-cli ${VERSION}\n`);
             return;

package/dist/update.js

@@ -0,0 +1,126 @@
+import { spawn } from 'node:child_process';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { configDir } from './config.js';
+const REGISTRY_LATEST_URL = 'https://registry.npmjs.org/@memoring%2Fcli/latest';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 8000;
+function cachePath() {
+    return join(configDir(), 'update-check.json');
+}
+function readCache() {
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath(), 'utf8'));
+        if (typeof parsed.checkedAt !== 'number') {
+            return null;
+        }
+        return {
+            checkedAt: parsed.checkedAt,
+            latest: typeof parsed.latest === 'string' ? parsed.latest : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(latest) {
+    try {
+        mkdirSync(dirname(cachePath()), { recursive: true });
+        const tmp = `${cachePath()}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify({ checkedAt: Date.now(), latest }));
+        renameSync(tmp, cachePath());
+    }
+    catch {
+        // cache é best-effort — nunca atrapalhar o comando em execução
+    }
+}
+/** true quando `latest` é semver maior que `current` (comparação numérica de x.y.z). */
+export function isNewerVersion(latest, current) {
+    const parts = (v) => v.replace(/^v/, '').split('.').map((p) => Number.parseInt(p, 10) || 0);
+    const a = parts(latest);
+    const b = parts(current);
+    for (let i = 0; i < 3; i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x !== y) {
+            return x > y;
+        }
+    }
+    return false;
+}
+/** Versão mais nova segundo o cache local, ou null (cache ausente/stale não é erro). */
+export function newerVersionAvailable(current) {
+    const cache = readCache();
+    return cache?.latest && isNewerVersion(cache.latest, current) ? cache.latest : null;
+}
+/** Consulta o registry na hora (usado pelo `memoring update`). Null quando offline/indisponível. */
+export async function fetchLatestVersion() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const response = await fetch(REGISTRY_LATEST_URL, {
+            signal: controller.signal,
+            headers: { accept: 'application/json' },
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const body = (await response.json());
+        return typeof body.version === 'string' ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Grava o cache (após self-update bem-sucedido, suprime o aviso na hora). */
+export function recordUpdateCheck(latest) {
+    writeCache(latest);
+}
+/**
+ * Agenda a verificação periódica: um processo filho detached faz o fetch e grava
+ * o cache — o comando em execução nunca espera a rede e nunca vê erro (offline ok).
+ * No máximo uma verificação a cada 24h; MEMORING_NO_UPDATE_CHECK=1 desativa.
+ */
+export function scheduleUpdateCheck() {
+    if (process.env.MEMORING_NO_UPDATE_CHECK) {
+        return;
+    }
+    const cache = readCache();
+    if (cache && Date.now() - cache.checkedAt < CHECK_INTERVAL_MS) {
+        return;
+    }
+    const script = `
+const [cachePath, previous] = process.argv.slice(1);
+const fs = require('node:fs');
+const path = require('node:path');
+const writeCache = (latest) => {
+  try {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    const tmp = cachePath + '.' + process.pid + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify({ checkedAt: Date.now(), latest: latest || undefined }));
+    fs.renameSync(tmp, cachePath);
+  } catch {}
+};
+const controller = new AbortController();
+const timer = setTimeout(() => controller.abort(), ${FETCH_TIMEOUT_MS});
+fetch(${JSON.stringify(REGISTRY_LATEST_URL)}, { signal: controller.signal, headers: { accept: 'application/json' } })
+  .then((r) => (r.ok ? r.json() : null))
+  .then((b) => writeCache(b && typeof b.version === 'string' ? b.version : previous))
+  .catch(() => writeCache(previous))
+  .finally(() => clearTimeout(timer));
+`;
+    try {
+        const child = spawn(process.execPath, ['-e', script, cachePath(), cache?.latest ?? ''], {
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        child.unref();
+    }
+    catch {
+        // verificação é best-effort
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memoring/cli",
-  "version": "0.2.0",
+  "version": "0.4.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

@@ -25,6 +25,7 @@ O Memoring é um app de estudos com revisão espaçada (FSRS). A CLI `memoring`
 - `type`: `NOTE` (nota, exige `content` markdown; `NORMAL` legado é aceito e mapeado para `NOTE`), `FLASHCARD` ou `ONE_SHOT` (exigem `front` + `back`).
 - `title` sempre obrigatório; lote de 1 a 50 itens, all-or-nothing.
 - Se o usuário pedir limites por tipo (ex.: "no máximo 20 flashcards e 5 notas"), respeite-os ao gerar e valide com `--max-notes N --max-flashcards N --max-one-shots N` no `stage create` — o lote é rejeitado se exceder.
+- O `stage schema` mostra os **limites por tipo do usuário** (`userCaps` no JSON; texto no fim da saída em modo humano) — respeite-os ao gerar, mesmo sem pedido explícito no chat. Sem limites visíveis, o create ainda pode rejeitar pela preferência gravada: ajuste o lote e reenvie. Para MUDAR a preferência permanente, o usuário roda `memoring stage caps` — não rode por conta própria.
 - `ONE_SHOT` = pergunta de resposta única; prefira `FLASHCARD` para memorização.
 - Preencha `source` com a origem real do material (nome do arquivo/pasta) — não use o default quando souber a origem.
 - `subjectName`/`subtopicName` quando o material tiver matéria/subtópico claros; `tags` curtas e em minúsculas.
@@ -33,6 +34,7 @@ O Memoring é um app de estudos com revisão espaçada (FSRS). A CLI `memoring`
 ## Armadilhas
 
 - **Nunca** use `--replace` sem o usuário pedir explicitamente — ele apaga os itens pendentes existentes da caixa.
+- 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.
 - Se `stage create` falhar com erro de validação do servidor, corrija os itens indicados e reenvie — não relaxe o contrato.
 - Lotes grandes: divida em vários arquivos de até 50 itens e envie sequencialmente.
 - Flashcards bons são atômicos: uma ideia por cartão, pergunta direta, resposta completa mas curta.