@soltaoverbo/cli 0.3.0 → 0.4.0

package/dist/bin.js

@@ -3,11 +3,8 @@
 // src/bin.ts
 import { execSync } from "child_process";
 
-// src/commands/install.ts
-import { existsSync, readFileSync, writeFileSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
-import { buildTermIndex, loadTerms, SpacedRepetition } from "@soltaoverbo/core";
+// src/commands/config.ts
+import { getApiKey, setApiKey } from "@soltaoverbo/core";
 
 // src/ui.ts
 var R = "\x1B[0m";
@@ -22,7 +19,101 @@ function progressBar(pct, width) {
   return `\x1B[32m${"█".repeat(filled)}\x1B[2m${"░".repeat(empty)}${R}`;
 }
 
+// src/commands/config.ts
+function runConfig(args) {
+  const [subcmd, ...rest2] = args;
+  switch (subcmd) {
+    case "set-key": {
+      const key = rest2[0];
+      if (!key) {
+        console.error(`${bold("Uso:")} verbo config set-key <chave>`);
+        process.exit(1);
+      }
+      setApiKey(key);
+      console.log(`${bold("[verbo]")} API key salva em ${dim("~/.verbo/config.json")}`);
+      break;
+    }
+    case "show-key": {
+      const key = getApiKey();
+      if (!key) {
+        console.log(dim("Nenhuma API key configurada."));
+      } else {
+        console.log(`API key: ${cyan(`${key.slice(0, 8)}...${key.slice(-4)}`)}`);
+      }
+      break;
+    }
+    default:
+      console.log(
+        `${bold("verbo config")} — configurações do verbo
+
+  ${bold("set-key")} ${dim("<chave>")}   Salva a API key da Anthropic em ~/.verbo/config.json
+  ${bold("show-key")}            Exibe a API key atual (parcial)
+`
+      );
+  }
+}
+
+// src/commands/explain.ts
+import { createInterface } from "readline";
+import { readFileSync } from "fs";
+import { basename, extname } from "path";
+import { explainCode, getApiKey as getApiKey2, hasConsented, injectExplanations, setConsented } from "@soltaoverbo/core";
+async function runExplain(args) {
+  const filePath = args[0];
+  if (!filePath) {
+    console.error(`${bold("Uso:")} verbo explain <arquivo>`);
+    process.exit(1);
+  }
+  const apiKey = getApiKey2();
+  if (!apiKey) {
+    console.error(
+      `${bold("verbo explain")} requer uma API key da Anthropic.
+Configure com: ${cyan("verbo config set-key <sua-chave>")}
+Obtenha sua chave em: https://console.anthropic.com/`
+    );
+    process.exit(1);
+  }
+  if (!hasConsented()) {
+    const confirmed = await askConsent(basename(filePath));
+    if (!confirmed) {
+      console.error("Operação cancelada.");
+      process.exit(0);
+    }
+    setConsented();
+  }
+  let code;
+  try {
+    code = readFileSync(filePath, "utf-8");
+  } catch {
+    console.error(`Não foi possível ler o arquivo: ${filePath}`);
+    process.exit(1);
+  }
+  const lang = extname(filePath).replace(".", "") || "código";
+  process.stderr.write(dim(`[verbo] Explicando ${basename(filePath)}...
+`));
+  const explanations = await explainCode(code, lang, apiKey);
+  const annotated = injectExplanations(code, explanations);
+  process.stdout.write(annotated + "\n");
+}
+function askConsent(fileName) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(
+      `${bold("[verbo]")} O conteúdo de ${cyan(fileName)} será enviado para a API da Anthropic.
+         Esta mensagem só aparece uma vez. Continuar? (s/N): `,
+      (answer) => {
+        rl.close();
+        resolve(answer.trim().toLowerCase() === "s");
+      }
+    );
+  });
+}
+
 // src/commands/install.ts
+import { existsSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { buildTermIndex, loadTerms, SpacedRepetition } from "@soltaoverbo/core";
 var CLAUDE_SETTINGS = join(homedir(), ".claude", "settings.json");
 var VERBO_PREFIX = "verbo · ";
 function runInstall() {
@@ -30,7 +121,7 @@ function runInstall() {
     console.error(`Claude Code não encontrado em ${CLAUDE_SETTINGS}`);
     process.exit(1);
   }
-  const settings = JSON.parse(readFileSync(CLAUDE_SETTINGS, "utf-8"));
+  const settings = JSON.parse(readFileSync2(CLAUDE_SETTINGS, "utf-8"));
   const sr = new SpacedRepetition();
   const allTerms = buildTermIndex(loadTerms());
   const absorbed = sr.absorbedIds();
@@ -110,10 +201,10 @@ function runList(args) {
 }
 
 // src/commands/reset.ts
-import { createInterface } from "readline";
+import { createInterface as createInterface2 } from "readline";
 import { SpacedRepetition as SpacedRepetition3 } from "@soltaoverbo/core";
 async function runReset() {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const rl = createInterface2({ input: process.stdin, output: process.stdout });
   await new Promise((resolve) => {
     rl.question(
       `${yellow("⚠")}  Isso apagará todo o histórico de aprendizado. Confirmar? ${dim("[s/N]")} `,
@@ -132,9 +223,9 @@ async function runReset() {
 }
 
 // src/commands/start.ts
-import { createInterface as createInterface2 } from "readline";
-import { readFileSync as readFileSync2 } from "fs";
-import { extname } from "path";
+import { createInterface as createInterface3 } from "readline";
+import { readFileSync as readFileSync3 } from "fs";
+import { extname as extname2 } from "path";
 import {
   buildTermIndex as buildTermIndex2,
   injectComments,
@@ -187,7 +278,7 @@ async function runStart(args) {
   }
 }
 async function pipeMode(sr, terms) {
-  const rl = createInterface2({ input: process.stdin, terminal: false });
+  const rl = createInterface3({ input: process.stdin, terminal: false });
   const lines = [];
   for await (const line of rl) lines.push(line);
   const seenTerms = sr.absorbedIds();
@@ -211,10 +302,10 @@ async function watchMode(dir, extensions, sr, terms) {
     awaitWriteFinish: { stabilityThreshold: 150, pollInterval: 50 }
   });
   const handle = (filePath) => {
-    if (!extensions.has(extname(filePath))) return;
+    if (!extensions.has(extname2(filePath))) return;
     let source;
     try {
-      source = readFileSync2(filePath, "utf-8");
+      source = readFileSync3(filePath, "utf-8");
     } catch {
       return;
     }
@@ -301,6 +392,8 @@ function help() {
   ${bold("COMANDOS")}
     ${bold("start")}                  Modo pipe: lê stdin e injeta comentários em pt-BR
     ${bold("start --watch")} ${dim("<dir>")}   Observa diretório e loga termos novos no terminal
+    ${bold("explain")} ${dim("<arquivo>")}      Explica o código linha por linha via IA (pt-BR)
+    ${bold("config set-key")} ${dim("<chave>")} Salva a API key da Anthropic
     ${bold("stats")}                  Mostra seu progresso de aprendizado
     ${bold("stats --short")}          Saída compacta para status bars
     ${bold("install")}                Injeta termos no Claude Code (barra de pensamento)
@@ -312,6 +405,8 @@ function help() {
   ${bold("EXEMPLOS")}
     cat handler.ts | verbo start
     verbo start --watch ./src
+    verbo explain handler.ts
+    verbo config set-key sk-ant-...
     verbo stats
     verbo install
     verbo list --category backend
@@ -325,6 +420,12 @@ switch (sub) {
   case "start":
     await runStart(rest);
     break;
+  case "explain":
+    await runExplain(rest);
+    break;
+  case "config":
+    runConfig(rest);
+    break;
   case "stats":
     runStats(rest);
     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soltaoverbo/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CLI para verbo.dev — aprenda inglês técnico passivamente",
   "bin": {
     "verbo": "./dist/bin.js"
@@ -8,7 +8,7 @@
   "type": "module",
   "dependencies": {
     "chokidar": "^3.6.0",
-    "@soltaoverbo/core": "0.3.0"
+    "@soltaoverbo/core": "0.4.0"
   },
   "devDependencies": {
     "tsup": "^8.3.5",

package/src/bin.ts

@@ -1,4 +1,6 @@
 import { execSync } from "node:child_process"
+import { runConfig } from "./commands/config.ts"
+import { runExplain } from "./commands/explain.ts"
 import { runInstall } from "./commands/install.ts"
 import { runList } from "./commands/list.ts"
 import { runReset } from "./commands/reset.ts"
@@ -34,6 +36,8 @@ function help(): void {
   ${bold("COMANDOS")}
     ${bold("start")}                  Modo pipe: lê stdin e injeta comentários em pt-BR
     ${bold("start --watch")} ${dim("<dir>")}   Observa diretório e loga termos novos no terminal
+    ${bold("explain")} ${dim("<arquivo>")}      Explica o código linha por linha via IA (pt-BR)
+    ${bold("config set-key")} ${dim("<chave>")} Salva a API key da Anthropic
     ${bold("stats")}                  Mostra seu progresso de aprendizado
     ${bold("stats --short")}          Saída compacta para status bars
     ${bold("install")}                Injeta termos no Claude Code (barra de pensamento)
@@ -45,6 +49,8 @@ function help(): void {
   ${bold("EXEMPLOS")}
     cat handler.ts | verbo start
     verbo start --watch ./src
+    verbo explain handler.ts
+    verbo config set-key sk-ant-...
     verbo stats
     verbo install
     verbo list --category backend
@@ -59,6 +65,12 @@ switch (sub) {
   case "start":
     await runStart(rest)
     break
+  case "explain":
+    await runExplain(rest)
+    break
+  case "config":
+    runConfig(rest)
+    break
   case "stats":
     runStats(rest)
     break

package/src/commands/config.ts

@@ -0,0 +1,35 @@
+import { getApiKey, setApiKey } from "@soltaoverbo/core"
+import { bold, cyan, dim } from "../ui.ts"
+
+export function runConfig(args: string[]): void {
+  const [subcmd, ...rest] = args
+
+  switch (subcmd) {
+    case "set-key": {
+      const key = rest[0]
+      if (!key) {
+        console.error(`${bold("Uso:")} verbo config set-key <chave>`)
+        process.exit(1)
+      }
+      setApiKey(key)
+      console.log(`${bold("[verbo]")} API key salva em ${dim("~/.verbo/config.json")}`)
+      break
+    }
+    case "show-key": {
+      const key = getApiKey()
+      if (!key) {
+        console.log(dim("Nenhuma API key configurada."))
+      } else {
+        // Show only first 8 and last 4 chars — never log the full key
+        console.log(`API key: ${cyan(`${key.slice(0, 8)}...${key.slice(-4)}`)}`)
+      }
+      break
+    }
+    default:
+      console.log(
+        `${bold("verbo config")} — configurações do verbo\n\n` +
+        `  ${bold("set-key")} ${dim("<chave>")}   Salva a API key da Anthropic em ~/.verbo/config.json\n` +
+        `  ${bold("show-key")}            Exibe a API key atual (parcial)\n`,
+      )
+  }
+}

package/src/commands/explain.ts

@@ -0,0 +1,62 @@
+import { createInterface } from "node:readline"
+import { readFileSync } from "node:fs"
+import { basename, extname } from "node:path"
+import { explainCode, getApiKey, hasConsented, injectExplanations, setConsented } from "@soltaoverbo/core"
+import { bold, cyan, dim } from "../ui.ts"
+
+export async function runExplain(args: string[]): Promise<void> {
+  const filePath = args[0]
+  if (!filePath) {
+    console.error(`${bold("Uso:")} verbo explain <arquivo>`)
+    process.exit(1)
+  }
+
+  const apiKey = getApiKey()
+  if (!apiKey) {
+    console.error(
+      `${bold("verbo explain")} requer uma API key da Anthropic.\n` +
+      `Configure com: ${cyan("verbo config set-key <sua-chave>")}\n` +
+      `Obtenha sua chave em: https://console.anthropic.com/`,
+    )
+    process.exit(1)
+  }
+
+  if (!hasConsented()) {
+    const confirmed = await askConsent(basename(filePath))
+    if (!confirmed) {
+      console.error("Operação cancelada.")
+      process.exit(0)
+    }
+    setConsented()
+  }
+
+  let code: string
+  try {
+    code = readFileSync(filePath, "utf-8")
+  } catch {
+    console.error(`Não foi possível ler o arquivo: ${filePath}`)
+    process.exit(1)
+  }
+
+  const lang = extname(filePath).replace(".", "") || "código"
+
+  process.stderr.write(dim(`[verbo] Explicando ${basename(filePath)}...\n`))
+
+  const explanations = await explainCode(code, lang, apiKey)
+  const annotated = injectExplanations(code, explanations)
+  process.stdout.write(annotated + "\n")
+}
+
+function askConsent(fileName: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr })
+    rl.question(
+      `${bold("[verbo]")} O conteúdo de ${cyan(fileName)} será enviado para a API da Anthropic.\n` +
+      `         Esta mensagem só aparece uma vez. Continuar? (s/N): `,
+      (answer) => {
+        rl.close()
+        resolve(answer.trim().toLowerCase() === "s")
+      },
+    )
+  })
+}