@memoring/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @memoring/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CLI do [Memoring](https://memoring.com.br) — envie flashcards e notas gerados por IA para a sua caixa de revisão, direto do terminal.
+
+A CLI não tem LLM própria: quem lê o material e gera os flashcards é o seu agente de IA (Kimi Code, Claude Code, etc.). A CLI cuida da parte mecânica — autenticar, expor o contrato JSON e enviar o resultado para o app, onde você revisa e aceita cada item.
+
+## Install
+
+```
+npm install -g @memoring/cli
+```
+
+## Quickstart
+
+Autentique (abre o browser — sem senha no terminal):
+
+```
+memoring auth login
+```
+
+Peça ao seu agente de IA:
+
+> use a cli do memoring pra criar flashcards dos materiais na pasta ./apostilas
+
+Ou faça na mão:
+
+```
+memoring stage schema                      # o contrato JSON dos itens
+memoring stage create --file itens.json    # envia o lote para a caixa de revisão
+memoring inbox list                        # o que está pendente
+memoring inbox accept-all                  # aceita tudo (entra na fila FSRS)
+```
+
+Os itens enviados nascem **PENDING_REVIEW** — nada entra nas suas listagens nem na fila de revisão espaçada até você aceitar em [memoring.com.br/cards/inbox](https://memoring.com.br/cards/inbox) ou via `memoring inbox accept`.
+
+## Como funciona
+
+1. **Você** roda `memoring auth login` uma vez (device flow do Keycloak — o token fica em `~/.config/memoring/config.json`, ou `%APPDATA%\memoring` no Windows).
+2. **O agente** lê seus PDFs/textos/anotações, gera os itens no contrato (`memoring stage schema`) e envia com `memoring stage create`.
+3. **Você** revisa e aceita no app (ou pelo terminal). FLASHCARDs e ONE_SHOTs aceitos entram na fila de revisão espaçada FSRS.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `memoring auth` | login / logout / status |
+| `memoring stage` | schema (o contrato) / create (envia o lote, `--file` ou stdin, `--replace` esvazia a caixa antes) |
+| `memoring inbox` | list / accept `<id>` / accept-all / discard `<id>` |
+| `memoring version` | versão da CLI |
+
+## Flags
+
+| Flag | Purpose |
+| --- | --- |
+| `--json` | saída legível por máquina (para agentes e pipes) |
+| `--no-color` | desativa cores |
+| `--no-open` | (auth login) não abre o browser automaticamente |
+| `--api-base` | sobrescreve a URL da API |
+
+Exemplo de pipeline:
+
+```
+memoring inbox list --json | jq -r '.[].id' | xargs -n1 memoring inbox discard
+```
+
+## O contrato (`memoring stage schema`)
+
+Cada item do lote (1 a 50, all-or-nothing):
+
+```json
+{
+  "type": "FLASHCARD",
+  "title": "CF/88 — objetivos fundamentais",
+  "front": "Quais são os quatro objetivos fundamentais da República (art. 3º da CF/88)?",
+  "back": "I — construir uma sociedade livre, justa e solidária; II — garantir o desenvolvimento nacional; III — erradicar a pobreza e reduzir as desigualdades; IV — promover o bem de todos.",
+  "subjectName": "Direito Constitucional",
+  "tags": ["cf88", "art-3"],
+  "source": "Apostila constitucional.pdf"
+}
+```
+
+- `type`: `NORMAL` (nota, exige `content` em markdown), `FLASHCARD` ou `ONE_SHOT` (exigem `front` + `back`).
+- `source`: origem do material — default `"Importação assistida (CLI)"`.
+
+## Para agentes de IA
+
+Este pacote inclui uma skill em `skills/memoring-cli/SKILL.md` com o fluxo completo (auth → schema → gerar → stage → avisar o usuário). Aponte o agente para ela, ou simplesmente peça "use a cli do memoring" — os comandos são auto-descritivos (`--help` em todos).
+
+## Dev (backend local)
+
+```
+MEMORING_API_BASE=http://localhost:8085/api \
+MEMORING_KEYCLOAK_URL=http://localhost:8080 \
+memoring auth login
+```
+
+Variáveis: `MEMORING_API_BASE`, `MEMORING_KEYCLOAK_URL`, `MEMORING_KC_REALM`, `MEMORING_KC_CLIENT`, `MEMORING_CONFIG_HOME` (isola o config.json).
+
+Build a partir do repo: `cd cli && npm install && npm run build && node dist/main.js --help`.

package/dist/api.js

@@ -0,0 +1,36 @@
+import { getAccessToken } from './auth.js';
+import { loadConfig } from './config.js';
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`HTTP ${status}: ${body}`);
+        this.status = status;
+        this.body = body;
+    }
+}
+/** 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();
+    const url = `${cfg.apiBase}${path}`;
+    const doFetch = async (token) => fetch(url, {
+        method: options.method ?? 'GET',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            ...(options.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        },
+        body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+    });
+    let res = await doFetch(await getAccessToken());
+    if (res.status === 401) {
+        res = await doFetch(await getAccessToken({ forceRefresh: true }));
+    }
+    if (res.status === 204) {
+        return null;
+    }
+    const text = await res.text();
+    if (!res.ok) {
+        throw new ApiError(res.status, text);
+    }
+    return text ? JSON.parse(text) : null;
+}

package/dist/args.js

@@ -0,0 +1,36 @@
+const BOOLEAN_FLAGS = new Set(['json', 'no-color', 'replace', 'help', 'version', 'no-open']);
+export function parseArgs(argv) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith('--')) {
+            const eq = arg.indexOf('=');
+            if (eq !== -1) {
+                flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+                continue;
+            }
+            const name = arg.slice(2);
+            if (BOOLEAN_FLAGS.has(name)) {
+                flags[name] = true;
+                continue;
+            }
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('--')) {
+                flags[name] = next;
+                i++;
+            }
+            else {
+                flags[name] = true;
+            }
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { _: positional, flags };
+}
+export function stringFlag(flags, name) {
+    const value = flags[name];
+    return typeof value === 'string' ? value : undefined;
+}

package/dist/auth.js

@@ -0,0 +1,153 @@
+import { exec } from 'node:child_process';
+import { loadConfig, saveSession, saveTokens } 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';
+function realmBase(cfg) {
+    return `${cfg.keycloakUrl}/realms/${cfg.realm}`;
+}
+function deviceUrl(cfg) {
+    return `${realmBase(cfg)}/protocol/openid-connect/auth/device`;
+}
+function tokenUrl(cfg) {
+    return `${realmBase(cfg)}/protocol/openid-connect/token`;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function decodeJwtEmail(token) {
+    try {
+        const payload = token.split('.')[1];
+        if (!payload) {
+            return undefined;
+        }
+        const json = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        return (json.email ?? json.preferred_username);
+    }
+    catch {
+        return undefined;
+    }
+}
+function openBrowser(url) {
+    const command = process.platform === 'win32'
+        ? `start "" "${url}"`
+        : process.platform === 'darwin'
+            ? `open "${url}"`
+            : `xdg-open "${url}"`;
+    exec(command, () => {
+        // melhor esforço — a URL já está impressa no terminal
+    });
+}
+async function requestToken(cfg, params) {
+    return fetch(tokenUrl(cfg), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ client_id: cfg.clientId, ...params }),
+    });
+}
+/** Device Authorization Grant (RFC 8628): mostra o código, abre o browser e faz poll até aprovar. */
+export async function deviceLogin(options = {}) {
+    const cfg = loadConfig();
+    const res = await fetch(deviceUrl(cfg), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ client_id: cfg.clientId, scope: 'openid profile email' }),
+    });
+    if (!res.ok) {
+        fail(`não foi possível iniciar o login (${res.status}): ${await res.text()}`);
+    }
+    const device = (await res.json());
+    process.stdout.write('\nPara entrar no Memoring, acesse:\n\n');
+    process.stdout.write(`  ${cyan(device.verification_uri)}\n\n`);
+    process.stdout.write(`e informe o código:  ${bold(device.user_code)}\n`);
+    if (device.verification_uri_complete) {
+        process.stdout.write(dim(`\n(ou abra direto: ${device.verification_uri_complete})\n`));
+        if (!options.noOpen) {
+            openBrowser(device.verification_uri_complete);
+        }
+    }
+    process.stdout.write(dim('\nAguardando aprovação…\n'));
+    let intervalMs = (device.interval ?? 5) * 1000;
+    const deadline = Date.now() + device.expires_in * 1000;
+    for (;;) {
+        if (Date.now() >= deadline) {
+            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 });
+        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,
+            }, {
+                accessToken: tokens.access_token,
+                refreshToken: tokens.refresh_token,
+                accessTokenExpiresAt: Date.now() + tokens.expires_in * 1000,
+                email,
+            });
+            return email;
+        }
+        const err = (await poll.json().catch(() => ({})));
+        switch (err.error) {
+            case 'authorization_pending':
+                continue;
+            case 'slow_down':
+                intervalMs += 5000;
+                continue;
+            case 'access_denied':
+                fail('login negado no navegador.');
+                break;
+            case 'expired_token':
+                fail('o código expirou — rode `memoring auth login` de novo.');
+                break;
+            default:
+                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;
+    }
+    if (!cfg.refreshToken) {
+        fail('você não está autenticado. Rode `memoring auth login`.');
+    }
+    const res = await requestToken(cfg, { grant_type: 'refresh_token', refresh_token: cfg.refreshToken });
+    if (!res.ok) {
+        fail('sessão expirada. Rode `memoring auth login`.');
+    }
+    const tokens = (await res.json());
+    saveTokens({
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token ?? cfg.refreshToken,
+        accessTokenExpiresAt: Date.now() + tokens.expires_in * 1000,
+        email: decodeJwtEmail(tokens.access_token) ?? cfg.email,
+    });
+    return tokens.access_token;
+}
+/** Logout no Keycloak (melhor esforço) — revoga o refresh token. */
+export async function serverLogout() {
+    const cfg = loadConfig();
+    if (!cfg.refreshToken) {
+        return;
+    }
+    try {
+        await fetch(`${realmBase(cfg)}/protocol/openid-connect/logout`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({ client_id: cfg.clientId, refresh_token: cfg.refreshToken }),
+        });
+    }
+    catch {
+        // melhor esforço — a sessão local já será removida
+    }
+}

package/dist/commands/auth.js

@@ -0,0 +1,77 @@
+import { clearSession, hasSession, loadConfig } from '../config.js';
+import { deviceLogin, serverLogout } from '../auth.js';
+import { apiFetch } from '../api.js';
+import { bold, dim, green, printJson, red, yellow } from './shared.js';
+export async function authCommand(parsed) {
+    const [sub] = parsed._;
+    switch (sub) {
+        case 'login': {
+            if (hasSession()) {
+                process.stdout.write(yellow('Já existe uma sessão salva — ela será substituída.\n'));
+            }
+            const email = await deviceLogin({ noOpen: Boolean(parsed.flags['no-open']) });
+            process.stdout.write(green(`\nAutenticado${email ? ` como ${bold(email)}` : ''}.\n`));
+            return;
+        }
+        case 'logout': {
+            await serverLogout();
+            clearSession();
+            process.stdout.write('Sessão removida.\n');
+            return;
+        }
+        case 'status': {
+            const cfg = loadConfig();
+            if (!hasSession()) {
+                if (parsed.flags.json) {
+                    printJson({ authenticated: false });
+                    return;
+                }
+                process.stdout.write('Não autenticado. Rode `memoring auth login`.\n');
+                process.exitCode = 1;
+                return;
+            }
+            let pending;
+            let valid = true;
+            try {
+                const inbox = (await apiFetch('/notes/review-inbox'));
+                pending = inbox.length;
+            }
+            catch {
+                valid = false;
+            }
+            const status = {
+                authenticated: valid,
+                email: cfg.email,
+                apiBase: cfg.apiBase,
+                keycloakUrl: cfg.keycloakUrl,
+                realm: cfg.realm,
+                clientId: cfg.clientId,
+                pendingReview: pending,
+            };
+            if (parsed.flags.json) {
+                printJson(status);
+                if (!valid) {
+                    process.exitCode = 1;
+                }
+                return;
+            }
+            if (!valid) {
+                process.stdout.write(red('Sessão inválida ou expirada. Rode `memoring auth login`.\n'));
+                process.exitCode = 1;
+                return;
+            }
+            process.stdout.write(`${green('Autenticado')}${cfg.email ? ` como ${bold(cfg.email)}` : ''}\n`);
+            process.stdout.write(dim(`API: ${cfg.apiBase} · Keycloak: ${cfg.keycloakUrl}/realms/${cfg.realm} · client: ${cfg.clientId}\n`));
+            process.stdout.write(dim(`Caixa de revisão: ${pending ?? 0} item(ns) pendente(s)\n`));
+            return;
+        }
+        default:
+            process.stdout.write('Uso: memoring auth <login|logout|status> [--no-open] [--json]\n' +
+                '  login    autentica via browser (device flow)\n' +
+                '  logout   remove a sessão local e revoga o token\n' +
+                '  status   mostra a sessão atual e itens pendentes de revisão\n');
+            if (sub) {
+                process.exitCode = 1;
+            }
+    }
+}

package/dist/commands/inbox.js

@@ -0,0 +1,78 @@
+import { apiFetch, ApiError } from '../api.js';
+import { fail, green, printJson, printTable } from './shared.js';
+async function listInbox() {
+    return (await apiFetch('/notes/review-inbox'));
+}
+export async function inboxCommand(parsed) {
+    const [sub, idArg] = parsed._;
+    switch (sub) {
+        case 'list': {
+            const notes = await listInbox();
+            if (parsed.flags.json) {
+                printJson(notes);
+                return;
+            }
+            if (notes.length === 0) {
+                process.stdout.write('Caixa de revisão vazia.\n');
+                return;
+            }
+            printTable(notes.map((n) => ({ id: `#${n.id}`, type: n.type, title: n.title })), [
+                { key: 'id', label: 'ID' },
+                { key: 'type', label: 'TIPO' },
+                { key: 'title', label: 'TÍTULO' },
+            ]);
+            process.stdout.write(`\n${notes.length} item(ns) pendente(s) — aceite em /cards/inbox ou com \`memoring inbox accept <id>\`.\n`);
+            return;
+        }
+        case 'accept':
+        case 'discard': {
+            const id = Number(idArg);
+            if (!idArg || !Number.isInteger(id) || id <= 0) {
+                fail(`informe o id numérico do item: memoring inbox ${sub} <id> (veja os ids com \`memoring inbox list\`).`);
+            }
+            try {
+                if (sub === 'accept') {
+                    const note = (await apiFetch(`/notes/review-inbox/${id}/accept`, { method: 'POST' }));
+                    if (parsed.flags.json) {
+                        printJson(note);
+                        return;
+                    }
+                    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' });
+                    if (parsed.flags.json) {
+                        printJson({ discarded: id });
+                        return;
+                    }
+                    process.stdout.write(green(`Item #${id} descartado.\n`));
+                }
+            }
+            catch (e) {
+                if (e instanceof ApiError && e.status === 404) {
+                    fail(`item #${id} não encontrado — confira \`memoring inbox list\`.`);
+                }
+                throw e;
+            }
+            return;
+        }
+        case 'accept-all': {
+            const res = (await apiFetch('/notes/review-inbox/accept-all', { method: 'POST' }));
+            if (parsed.flags.json) {
+                printJson(res);
+                return;
+            }
+            process.stdout.write(green(`${res.accepted} item(ns) aceito(s).\n`));
+            return;
+        }
+        default:
+            process.stdout.write('Uso: memoring inbox <list|accept|accept-all|discard> [id] [--json]\n' +
+                '  list        lista os itens pendentes de revisão\n' +
+                '  accept <id> aceita um item (entra nas listagens e na fila FSRS)\n' +
+                '  accept-all  aceita todos os itens pendentes\n' +
+                '  discard <id> descarta um item pendente\n');
+            if (sub) {
+                process.exitCode = 1;
+            }
+    }
+}

package/dist/commands/shared.js

@@ -0,0 +1,3 @@
+// Re-exports compartilhados para os comandos (evita import circular com main).
+export { parseArgs, stringFlag } from '../args.js';
+export { bold, dim, red, green, yellow, cyan, printJson, printTable, fail, setColorEnabled } from '../output.js';

package/dist/commands/stage.js

@@ -0,0 +1,161 @@
+import { readFileSync } from 'node:fs';
+import { apiFetch, ApiError } from '../api.js';
+import { dim, fail, green, printJson, stringFlag } from './shared.js';
+const TYPES = ['NORMAL', 'FLASHCARD', 'ONE_SHOT'];
+const MAX_ITEMS = 50;
+const DEFAULT_SOURCE = 'Importação assistida (CLI)';
+const SCHEMA_JSON = {
+    description: 'Lote de 1..50 itens para POST /api/notes/review-inbox. All-or-nothing: qualquer item inválido rejeita o lote. Os itens nascem PENDING_REVIEW — o usuário aceita/edita/recusa em /cards/inbox.',
+    item: {
+        type: 'NORMAL | FLASHCARD | ONE_SHOT (obrigatório)',
+        title: 'string (obrigatório)',
+        content: 'string — corpo da nota em markdown (obrigatório quando type=NORMAL)',
+        front: 'string — pergunta (obrigatório quando type=FLASHCARD|ONE_SHOT)',
+        back: 'string — resposta (obrigatório quando type=FLASHCARD|ONE_SHOT)',
+        subjectName: 'string? — matéria (ex.: "Direito Constitucional")',
+        subtopicName: 'string? — subtópico',
+        tags: 'string[]?',
+        source: `string? — origem do material (default: "${DEFAULT_SOURCE}")`,
+    },
+    example: [
+        {
+            type: 'FLASHCARD',
+            title: 'CF/88 — objetivos fundamentais',
+            front: 'Quais são os quatro objetivos fundamentais da República (art. 3º da CF/88)?',
+            back: 'I — construir uma sociedade livre, justa e solidária; II — garantir o desenvolvimento nacional; III — erradicar a pobreza e reduzir as desigualdades; IV — promover o bem de todos.',
+            subjectName: 'Direito Constitucional',
+            tags: ['cf88', 'art-3'],
+            source: 'Apostila constitucional.pdf',
+        },
+    ],
+};
+const SCHEMA_TEXT = `Contrato dos itens da caixa de revisão (POST /api/notes/review-inbox):
+
+  type          NORMAL | FLASHCARD | ONE_SHOT      (obrigatório)
+  title         string                            (obrigatório)
+  content       string — corpo da nota (markdown) (obrigatório quando type=NORMAL)
+  front, back   string — pergunta e resposta      (obrigatório quando type=FLASHCARD|ONE_SHOT)
+  subjectName?  string — matéria (ex.: "Direito Constitucional")
+  subtopicName? string — subtópico
+  tags?         string[]
+  source?       string — origem do material (default: "${DEFAULT_SOURCE}")
+
+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.`;
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function validateItems(raw) {
+    const items = Array.isArray(raw) ? raw : raw?.items;
+    if (!Array.isArray(items) || items.length === 0) {
+        fail('JSON inválido: esperado array não-vazio de itens ou { "items": [...] }. Rode `memoring stage schema` para ver o contrato.');
+    }
+    if (items.length > MAX_ITEMS) {
+        fail(`lote acima do limite: ${items.length} itens (máximo ${MAX_ITEMS}). Divida em mais de um lote.`);
+    }
+    return items.map((item, index) => {
+        const where = `item #${index + 1}`;
+        if (typeof item !== 'object' || item === null) {
+            fail(`${where}: esperado objeto, veio ${typeof item}.`);
+        }
+        const it = item;
+        if (typeof it.type !== 'string' || !TYPES.includes(it.type)) {
+            fail(`${where}: type deve ser ${TYPES.join(' | ')} (veio ${JSON.stringify(it.type)}).`);
+        }
+        if (typeof it.title !== 'string' || it.title.trim() === '') {
+            fail(`${where}: title é obrigatório.`);
+        }
+        if (it.type === 'NORMAL' && (typeof it.content !== 'string' || it.content.trim() === '')) {
+            fail(`${where} (${it.title}): type=NORMAL exige content.`);
+        }
+        if ((it.type === 'FLASHCARD' || it.type === 'ONE_SHOT') &&
+            (typeof it.front !== 'string' || it.front.trim() === '' || typeof it.back !== 'string' || it.back.trim() === '')) {
+            fail(`${where} (${it.title}): type=${it.type} exige front e back.`);
+        }
+        if (it.tags !== undefined && (!Array.isArray(it.tags) || it.tags.some((t) => typeof t !== 'string'))) {
+            fail(`${where} (${it.title}): tags deve ser um array de strings.`);
+        }
+        return { ...it, source: typeof it.source === 'string' && it.source.trim() !== '' ? it.source : DEFAULT_SOURCE };
+    });
+}
+async function emptyInbox() {
+    const pending = (await apiFetch('/notes/review-inbox'));
+    for (const note of pending) {
+        await apiFetch(`/notes/${note.id}`, { method: 'DELETE' });
+    }
+    return pending.length;
+}
+export async function stageCommand(parsed) {
+    const [sub] = parsed._;
+    switch (sub) {
+        case 'schema': {
+            if (parsed.flags.json) {
+                printJson(SCHEMA_JSON);
+            }
+            else {
+                process.stdout.write(SCHEMA_TEXT + '\n');
+            }
+            return;
+        }
+        case 'create': {
+            const file = stringFlag(parsed.flags, 'file');
+            let raw;
+            if (file && file !== '-') {
+                raw = readFileSync(file, 'utf8');
+            }
+            else if (!process.stdin.isTTY) {
+                raw = await readStdin();
+            }
+            else {
+                fail('informe o arquivo: memoring stage create --file itens.json (ou pipe via stdin).');
+            }
+            let parsedJson;
+            try {
+                parsedJson = JSON.parse(raw);
+            }
+            catch (e) {
+                fail(`JSON inválido: ${e.message}`);
+            }
+            const items = validateItems(parsedJson);
+            if (parsed.flags.replace) {
+                const removed = await emptyInbox();
+                if (!parsed.flags.json) {
+                    process.stdout.write(dim(`${removed} item(ns) pendente(s) removido(s) da caixa de revisão.\n`));
+                }
+            }
+            let created;
+            try {
+                const res = (await apiFetch('/notes/review-inbox', { method: 'POST', body: { items } }));
+                created = res.created;
+            }
+            catch (e) {
+                if (e instanceof ApiError) {
+                    fail(`o servidor rejeitou o lote (${e.status}): ${e.body}`);
+                }
+                throw e;
+            }
+            if (parsed.flags.json) {
+                printJson({ created });
+                return;
+            }
+            process.stdout.write(green(`OK — ${created.length} item(ns) aguardando revisão em /cards/inbox:\n`));
+            for (const note of created) {
+                process.stdout.write(`  #${note.id} [${note.type}] ${note.title}\n`);
+            }
+            return;
+        }
+        default:
+            process.stdout.write('Uso: memoring stage <schema|create> [--file itens.json] [--replace] [--json]\n' +
+                '  schema   imprime o contrato JSON dos itens (para humanos e agentes)\n' +
+                '  create   envia o lote para a caixa de revisão (arquivo ou stdin)\n' +
+                '           --replace esvazia a caixa antes de enviar\n');
+            if (sub) {
+                process.exitCode = 1;
+            }
+    }
+}

package/dist/config.js

@@ -0,0 +1,69 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const DEFAULTS = {
+    keycloakUrl: 'https://auth.memoring.com.br',
+    realm: 'memoring',
+    clientId: 'memoring-cli',
+    apiBase: 'https://memoring.com.br/api',
+};
+function configDir() {
+    if (process.env.MEMORING_CONFIG_HOME) {
+        return process.env.MEMORING_CONFIG_HOME;
+    }
+    if (process.platform === 'win32') {
+        return join(process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming'), 'memoring');
+    }
+    return join(homedir(), '.config', 'memoring');
+}
+function configPath() {
+    return join(configDir(), 'config.json');
+}
+function readStored() {
+    try {
+        return JSON.parse(readFileSync(configPath(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** Config efetiva: variáveis de ambiente sempre vencem o arquivo. */
+export function loadConfig() {
+    const stored = readStored();
+    return {
+        keycloakUrl: process.env.MEMORING_KEYCLOAK_URL ?? stored.keycloakUrl ?? DEFAULTS.keycloakUrl,
+        realm: process.env.MEMORING_KC_REALM ?? stored.realm ?? DEFAULTS.realm,
+        clientId: process.env.MEMORING_KC_CLIENT ?? stored.clientId ?? DEFAULTS.clientId,
+        apiBase: process.env.MEMORING_API_BASE ?? stored.apiBase ?? DEFAULTS.apiBase,
+        accessToken: stored.accessToken,
+        refreshToken: stored.refreshToken,
+        accessTokenExpiresAt: stored.accessTokenExpiresAt,
+        email: stored.email,
+    };
+}
+function writeStored(patch) {
+    const merged = { ...readStored(), ...patch };
+    mkdirSync(configDir(), { recursive: true });
+    writeFileSync(configPath(), JSON.stringify(merged, null, 2), { mode: 0o600 });
+}
+export function saveSession(endpoints, tokens) {
+    writeStored({ ...endpoints, ...tokens });
+}
+export function saveTokens(tokens) {
+    writeStored(tokens);
+}
+export function clearSession() {
+    const existed = existsSync(configPath());
+    const { accessToken, refreshToken, accessTokenExpiresAt, email, ...rest } = readStored();
+    void accessToken;
+    void refreshToken;
+    void accessTokenExpiresAt;
+    void email;
+    mkdirSync(configDir(), { recursive: true });
+    writeFileSync(configPath(), JSON.stringify(rest, null, 2), { mode: 0o600 });
+    return existed;
+}
+export function hasSession() {
+    const stored = readStored();
+    return Boolean(stored.accessToken ?? stored.refreshToken);
+}

package/dist/main.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { ApiError } from './api.js';
+import { setColorEnabled } from './output.js';
+import { authCommand } from './commands/auth.js';
+import { inboxCommand } from './commands/inbox.js';
+import { stageCommand } from './commands/stage.js';
+import { fail, parseArgs as parse } from './commands/shared.js';
+const VERSION = '0.1.0';
+const HELP = `Memoring CLI — flashcards e notas por IA, direto do terminal.
+
+Uso: memoring <comando> [subcomando] [flags]
+
+Comandos:
+  auth login|logout|status      autenticação (device flow — sem senha no terminal)
+  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
+  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
+  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)
+  --help, -h    ajuda
+
+Ambiente (dev): MEMORING_API_BASE, MEMORING_KEYCLOAK_URL, MEMORING_KC_REALM, MEMORING_KC_CLIENT
+
+Exemplos:
+  memoring auth login
+  memoring stage schema
+  cat itens.json | memoring stage create --json
+  memoring inbox list
+  memoring inbox accept-all
+`;
+async function main() {
+    const argv = process.argv.slice(2).map((a) => (a === '-h' ? '--help' : a));
+    const parsed = parse(argv);
+    if (parsed.flags['no-color'] || !process.stdout.isTTY) {
+        setColorEnabled(false);
+    }
+    const apiBase = typeof parsed.flags['api-base'] === 'string' ? parsed.flags['api-base'] : undefined;
+    if (apiBase) {
+        process.env.MEMORING_API_BASE = apiBase;
+    }
+    const [command, ...rest] = parsed._;
+    const sub = { _: rest, flags: parsed.flags };
+    if (parsed.flags.help || !command) {
+        process.stdout.write(HELP);
+        return;
+    }
+    switch (command) {
+        case 'auth':
+            await authCommand(sub);
+            return;
+        case 'stage':
+            await stageCommand(sub);
+            return;
+        case 'inbox':
+            await inboxCommand(sub);
+            return;
+        case 'version':
+            process.stdout.write(`memoring-cli ${VERSION}\n`);
+            return;
+        default:
+            process.stderr.write(`Comando desconhecido: ${command}\n\n`);
+            process.stdout.write(HELP);
+            process.exitCode = 1;
+    }
+}
+main().catch((error) => {
+    if (error instanceof ApiError) {
+        fail(`falha na API (${error.status}): ${error.body}`);
+    }
+    fail(error instanceof Error ? error.message : String(error));
+});

package/dist/output.js

@@ -0,0 +1,31 @@
+let colorEnabled = true;
+export function setColorEnabled(enabled) {
+    colorEnabled = enabled;
+}
+function paint(code) {
+    return (text) => (colorEnabled ? `[${code}m${text}` : text);
+}
+export const bold = paint(1);
+export const dim = paint(2);
+export const red = paint(31);
+export const green = paint(32);
+export const yellow = paint(33);
+export const cyan = paint(36);
+export function printJson(data) {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+export function printTable(rows, columns) {
+    if (rows.length === 0) {
+        return;
+    }
+    const widths = columns.map((col) => Math.max(col.label.length, ...rows.map((row) => String(row[col.key] ?? '').length)));
+    const renderRow = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join('  ').trimEnd();
+    process.stdout.write(dim(renderRow(columns.map((c) => c.label))) + '\n');
+    for (const row of rows) {
+        process.stdout.write(renderRow(columns.map((c) => String(row[c.key] ?? ''))) + '\n');
+    }
+}
+export function fail(message) {
+    process.stderr.write(red(`Erro: ${message}`) + '\n');
+    process.exit(1);
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@memoring/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "CLI do Memoring — envie flashcards/notas gerados por IA para a sua caixa de revisão, direto do terminal.",
+  "type": "module",
+  "bin": {
+    "memoring": "dist/main.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/main.js",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.0"
+  },
+  "license": "UNLICENSED"
+}

package/skills/memoring-cli/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: memoring-cli
+description: Gere flashcards e notas a partir de materiais de estudo locais (PDFs, textos, anotações) e envie para a caixa de revisão do Memoring usando a CLI `memoring`. Use quando o usuário pedir para "usar a cli do memoring", criar flashcards/notas de uma pasta ou arquivo, ou enviar material de estudo para o Memoring.
+---
+
+# Memoring CLI — geração de flashcards/notas por agente
+
+O Memoring é um app de estudos com revisão espaçada (FSRS). A CLI `memoring` é a ponte entre você (o agente, que lê o material e gera o conteúdo) e a conta do usuário no app. Você NÃO chama a API HTTP diretamente — use sempre a CLI.
+
+## Pré-requisitos
+
+1. CLI instalada: `memoring version` deve responder. Se não, peça ao usuário: `npm install -g @memoring/cli`.
+2. Sessão ativa: `memoring auth status --json` → `authenticated: true`. Se não, peça ao usuário para rodar `memoring auth login` (device flow — ele aprova no browser; você não consegue fazer isso por ele).
+
+## Fluxo
+
+1. **Entenda o pedido** — qual pasta/arquivo/material virar flashcards/notas.
+2. **Leia o contrato**: `memoring stage schema --json`.
+3. **Leia os materiais** e gere os itens no contrato, num arquivo JSON (array ou `{ "items": [...] }`).
+4. **Envie**: `memoring stage create --file <arquivo> --json`.
+5. **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`.
+
+## Regras do contrato (resumo — a fonte da verdade é `stage schema`)
+
+- `type`: `NORMAL` (nota, exige `content` markdown), `FLASHCARD` ou `ONE_SHOT` (exigem `front` + `back`).
+- `title` sempre obrigatório; lote de 1 a 50 itens, all-or-nothing.
+- `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.
+- NUNCA invente campos fora do contrato — o servidor rejeita o lote inteiro.
+
+## Armadilhas
+
+- **Nunca** use `--replace` sem o usuário pedir explicitamente — ele apaga os itens pendentes existentes da caixa.
+- 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.