@memoring/cli 0.2.0 → 0.3.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):
@@ -46,6 +56,7 @@ Os itens enviados nascem **PENDING_REVIEW** — nada entra nas suas listagens ne
 | `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 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
@@ -95,5 +106,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/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.3.0';
 const HELP = `Memoring CLI — flashcards e notas por IA, direto do terminal.
 
 Uso: memoring <comando> [subcomando] [flags]
@@ -18,16 +20,21 @@ Comandos:
   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 +52,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 +81,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.3.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

@@ -33,6 +33,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.