@ravox-ui/cli 0.1.0 → 0.2.0

package/README.md

@@ -8,6 +8,7 @@ npx @ravox-ui/cli add button dialog    # add components
 npx @ravox-ui/cli add dashboard-01     # add a block (a full screen, React)
 npx @ravox-ui/cli add --all            # add every component
 npx @ravox-ui/cli list                 # see everything available
+npx @ravox-ui/cli connect              # answer the site editors' chat with your own Claude Code
 ```
 
 Also with `pnpm dlx @ravox-ui/cli …`, `yarn dlx @ravox-ui/cli …` and `bunx @ravox-ui/cli …`.
@@ -21,9 +22,23 @@ Under the hood it uses the [shadcn](https://ui.shadcn.com) CLI with the Ravox re
 
 - **Framework:** detected from `package.json` (`--framework react|vue|svelte|angular` to choose).
   React gets the shadcn items; Vue, Svelte and Angular get their own ports, with the same API.
+- **React setup:** with Tailwind 4, a main CSS file and an import alias (`@/*`), `init` writes `components.json` itself,
+  so no component library (Radix, Base UI, React Aria) gets installed: the Kit uses none. Otherwise it runs `shadcn init`.
 - **Package manager:** shadcn runs with the one you used to call it (npx, pnpm, yarn or bun).
 - **Names:** `button`, `Button` or `button.json` all work, and typos get a suggestion.
 
+## Connect your Claude Code to the site editors
+
+`connect` (or `conectar`) links the component editor at ui.ravoxlabs.com/criar (and the team's video editor) to the
+[Claude Code](https://claude.com/claude-code) on your computer. You write in the editor's Claude chat; your Claude
+answers right there, the code and the preview update live, and follow-ups keep the context. It uses your own Claude
+subscription: no AI key, nothing to pay on the site.
+
+- The first run opens the browser to sign in and click **Allow** (OAuth with PKCE; the token is saved in
+  `~/.config/ravox-ui/conector.json`). `--login` signs in again; `--site <url>` points to another site.
+- Keep it open while you work (Ctrl+C turns it off). Each request runs `claude -p` with only the site's tools: it reads
+  and saves **your own drafts**, never publishes and touches no files on your computer.
+
 ## Options
 
 | Option | |
@@ -33,6 +48,9 @@ Under the hood it uses the [shadcn](https://ui.shadcn.com) CLI with the Ravox re
 | `-o, --overwrite` | overwrite existing files |
 | `-y, --yes` | skip confirmation prompts |
 | `--dry-run` | print the shadcn command, change nothing |
+| `--site <url>` | `connect`: the site (default `https://ui.ravoxlabs.com`) |
+| `--login` | `connect`: sign in again |
+| `--model <name>` | `connect`: Claude model (default `sonnet`; `opus` for harder work) |
 
 Messages are in Portuguese when your system language is Portuguese (`LANG=pt_BR…`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ravox-ui/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Add Ravox Kit components, blocks and themes to your project (React, Vue, Svelte and Angular).",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -1,16 +1,18 @@
 import { spawn } from "node:child_process";
-import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { conectar } from "./connect.mjs";
 import { messages } from "./messages.mjs";
-import { detectFramework, FRAMEWORKS, hasComponentsJson, readPackageJson, runnerFor } from "./project.mjs";
+import { detectFramework, FRAMEWORKS, hasComponentsJson, reactConfig, readPackageJson, runnerFor } from "./project.mjs";
 import { availableNames, fetchIndex, itemUrl, resolveNames, setupUrls } from "./registry.mjs";
 import { suggest } from "./suggest.mjs";
+import { keepTheme } from "./theme.mjs";
 
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
 /** Parses `command [names...] [--flags]`. */
 export function parseArgs(argv) {
-  const opts = { command: null, names: [], framework: null, cwd: process.cwd(), overwrite: false, yes: false, all: false, dryRun: false, help: false, version: false };
+  const opts = { command: null, names: [], framework: null, cwd: process.cwd(), overwrite: false, yes: false, all: false, dryRun: false, help: false, version: false, site: null, login: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     const value = () => {
@@ -27,6 +29,10 @@ export function parseArgs(argv) {
     else if (a === "-y" || a === "--yes") opts.yes = true;
     else if (a === "-a" || a === "--all") opts.all = true;
     else if (a === "--dry-run") opts.dryRun = true;
+    else if (a === "--site") opts.site = value();
+    else if (a.startsWith("--site=")) opts.site = a.slice(7);
+    else if (a === "--login") opts.login = true;
+    else if (a === "--model") opts.model = value();
     else if (!opts.command) opts.command = a;
     else opts.names.push(a);
   }
@@ -61,13 +67,27 @@ function frameworkOf(opts, t) {
   return fw;
 }
 
+/** Installs the theme into the main CSS without touching the variables the project already has (unless --overwrite). */
+async function runTheme(cmd, opts, t) {
+  if (opts.overwrite || opts.dryRun) return run(cmd, opts, t);
+  const { code, kept } = await keepTheme(opts.cwd, () => run(cmd, opts, t));
+  if (kept) console.log(t.keptVariables(kept));
+  return code;
+}
+
 async function init(opts, t) {
   const fw = frameworkOf(opts, t);
   if (fw === "react") {
     console.log(t.initReact);
-    // A project without components.json gets shadcn init (config + cn()) and the theme in one go.
-    const args = hasComponentsJson(opts.cwd) ? ["add", ...setupUrls(fw)] : ["init", ...setupUrls(fw)];
-    return run(shadcn(args, opts), opts, t);
+    if (hasComponentsJson(opts.cwd)) return runTheme(shadcn(["add", ...setupUrls(fw)], opts), opts, t);
+    // No components.json: we write it ourselves when the project is clear (Tailwind 4, CSS file, alias), so no
+    // base library comes along; the theme brings cn(). Otherwise shadcn init asks the user.
+    const config = reactConfig(opts.cwd, readPackageJson(opts.cwd));
+    if (!config) return runTheme(shadcn(["init", ...setupUrls(fw)], opts), opts, t);
+    if (opts.dryRun) console.log(`${t.dryRun} components.json ${JSON.stringify(config.aliases)}`);
+    else writeFileSync(join(opts.cwd, "components.json"), `${JSON.stringify(config, null, 2)}\n`);
+    console.log(t.wroteConfig(config.tailwind.css));
+    return runTheme(shadcn(["add", ...setupUrls(fw)], opts), opts, t);
   }
   console.log(t.initOther(fw));
   const code = await run(shadcn(["add", ...setupUrls(fw)], opts, t), opts, t);
@@ -128,6 +148,7 @@ export async function main(argv) {
   if (opts.command === "init") return init(opts, t);
   if (opts.command === "add") return add(opts, t);
   if (opts.command === "list" || opts.command === "ls") return list(opts, t);
+  if (opts.command === "conectar" || opts.command === "connect") return conectar(opts);
   console.error(t.unknownCommand(opts.command));
   return 1;
 }

package/src/connect.mjs

@@ -0,0 +1,384 @@
+// `ravox conectar`: links the Ravox UI site to the Claude Code installed on this computer. The editors' chat on the
+// site (components and video) gets answered right there, live, by the person's own Claude (their subscription),
+// with no AI key on the server. Login is the site's OAuth (PKCE, browser "Allow" page); each request runs
+// `claude -p` with the site's MCP tools and its progress goes back to the chat.
+
+import { execFile, spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { servidorLocal } from "./local.mjs";
+
+const CONFIG = join(homedir(), ".config", "ravox-ui", "conector.json");
+const INTERVALO = 2000;
+const PROGRESSO = 1200;
+
+const pt = /^pt/i.test(process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || Intl.DateTimeFormat().resolvedOptions().locale);
+const t = pt
+  ? {
+      semClaude: "Não achei o Claude Code neste computador. Instale com: npm i -g @anthropic-ai/claude-code (e entre com claude uma vez).",
+      abrindo: "Abrindo o navegador para você permitir o acesso (se não abrir, use este link):",
+      esperando: "Esperando você clicar em Permitir…",
+      recusado: "Acesso recusado no navegador.",
+      ligado: (site, quem) => `Conector ligado em ${site}${quem ? ` (${quem})` : ""}. Peça no chat do editor; deixe esta janela aberta. Ctrl+C desliga.`,
+      sessaoVencida: "A conexão venceu ou foi revogada; vamos entrar de novo.",
+      pedido: (texto) => `→ ${texto}`,
+      feito: "  feito",
+      erro: (m) => `  não deu: ${m}`,
+      falhaRede: (m) => `Sem conexão com o site (${m}); tento de novo em instantes.`,
+      pausado: "Desconectado no site: não pego pedidos até você clicar em Conectar no chat.",
+      retomado: "Conectado de novo no site.",
+      saiu: "Você saiu deste computador pelo site. Para ligar de novo: ravox conectar",
+    }
+  : {
+      semClaude: "Claude Code was not found on this computer. Install it with: npm i -g @anthropic-ai/claude-code (and sign in with claude once).",
+      abrindo: "Opening the browser so you can allow access (if it does not open, use this link):",
+      esperando: "Waiting for you to click Allow…",
+      recusado: "Access denied in the browser.",
+      ligado: (site, quem) => `Connector on for ${site}${quem ? ` (${quem})` : ""}. Ask in the editor chat; keep this window open. Ctrl+C turns it off.`,
+      sessaoVencida: "The connection expired or was revoked; signing in again.",
+      pedido: (texto) => `→ ${texto}`,
+      feito: "  done",
+      erro: (m) => `  failed: ${m}`,
+      falhaRede: (m) => `Cannot reach the site (${m}); retrying shortly.`,
+      pausado: "Disconnected on the site: no requests until you click Connect in the chat.",
+      retomado: "Connected again on the site.",
+      saiu: "You signed this computer out on the site. To turn it on again: ravox connect",
+    };
+
+const base64url = (b) => b.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+
+/* ---------------------------------------------------------------- saved login */
+
+function lerConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function salvarToken(site, token) {
+  const c = lerConfig();
+  c[site] = { token, em: new Date().toISOString() };
+  mkdirSync(dirname(CONFIG), { recursive: true });
+  writeFileSync(CONFIG, JSON.stringify(c, null, 2), { mode: 0o600 });
+}
+
+/* ---------------------------------------------------------------- login (OAuth + PKCE, localhost callback) */
+
+function abrirNavegador(url) {
+  const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  execFile(cmd, args, () => {});
+}
+
+export async function entrar(site) {
+  const verificador = base64url(randomBytes(32));
+  const desafio = base64url(createHash("sha256").update(verificador).digest());
+  const estado = base64url(randomBytes(16));
+
+  let receber;
+  const chegou = new Promise((r) => (receber = r));
+  // The browser waits on this response while the token is exchanged, then goes to the site's "connected" page.
+  const servidor = createServer((req, res) => {
+    const u = new URL(req.url ?? "/", "http://127.0.0.1");
+    if (u.pathname !== "/callback") return res.writeHead(404).end();
+    receber({ params: u.searchParams, res });
+  });
+  await new Promise((r) => servidor.listen(0, "127.0.0.1", r));
+  const volta = `http://127.0.0.1:${servidor.address().port}/callback`;
+
+  try {
+    const reg = await fetch(`${site}/api/oauth/registrar`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ client_name: "Ravox Conector", redirect_uris: [volta] }),
+    }).then((r) => r.json());
+    if (!reg.client_id) throw new Error(reg.error_description ?? "registro recusado");
+
+    const link = new URL(`${site}/oauth/autorizar`);
+    for (const [k, v] of Object.entries({
+      response_type: "code",
+      client_id: reg.client_id,
+      redirect_uri: volta,
+      code_challenge: desafio,
+      code_challenge_method: "S256",
+      state: estado,
+      resource: `${site}/api/mcp`,
+    }))
+      link.searchParams.set(k, v);
+    console.log(`${t.abrindo}\n  ${link}\n`);
+    abrirNavegador(link.toString());
+    console.log(t.esperando);
+
+    const { params: p, res } = await chegou;
+    const voltar = (ok) => res.writeHead(302, { location: `${site}/conector/pronto${ok ? "" : "?erro=1"}` }).end();
+    if (p.get("error") || p.get("state") !== estado || !p.get("code")) {
+      voltar(false);
+      throw new Error(t.recusado);
+    }
+    const tok = await fetch(`${site}/api/oauth/token`, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ grant_type: "authorization_code", code: p.get("code"), code_verifier: verificador, client_id: reg.client_id, redirect_uri: volta }),
+    }).then((r) => r.json());
+    if (!tok.access_token) {
+      voltar(false);
+      throw new Error(tok.error_description ?? "token recusado");
+    }
+    salvarToken(site, tok.access_token);
+    voltar(true);
+    return tok.access_token;
+  } finally {
+    servidor.close();
+  }
+}
+
+/* ---------------------------------------------------------------- the site's MCP */
+
+export class SemAcesso extends Error {}
+
+export async function chamar(site, token, nome, args = {}) {
+  const r = await fetch(`${site}/api/mcp`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/json", accept: "application/json, text/event-stream" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: nome === "tools/list" ? "tools/list" : "tools/call", params: nome === "tools/list" ? {} : { name: nome, arguments: args } }),
+  });
+  if (r.status === 401) throw new SemAcesso();
+  const j = await r.json();
+  if (j.error) throw new Error(j.error.message);
+  if (nome === "tools/list") return j.result.tools.map((f) => f.name);
+  if (j.result.isError) throw new Error(j.result.content?.[0]?.text ?? "erro");
+  return j.result.structuredContent;
+}
+
+/* ---------------------------------------------------------------- one request → claude -p */
+
+const SISTEMA = `Você atende pedidos escritos no editor do site Ravox UI pela dona ou dono da conta. Trabalhe só com as ferramentas do Ravox (mcp__ravox__* e, quando houver, mcp__local__*, que rodam neste computador): elas gravam direto no editor, que atualiza sozinho na tela da pessoa. Não chame as ferramentas responder_pedido_*: quem responde é o conector. Termine com 1 a 3 frases curtas em português do Brasil dizendo o que mudou (sem markdown pesado).`;
+
+/** What Claude gets for each request: the request, the target and (for components) the current code and the rules. */
+export function montarPedido(tipo, p, guia, comConversa = false, local = null) {
+  if (tipo === "componente") {
+    const c = p.componente;
+    const antes = comConversa && p.conversaAnterior?.length
+      ? `Conversa anterior neste componente (mais antiga primeiro):\n${p.conversaAnterior.map((x) => `- Pessoa: ${x.pedido}\n  Você: ${x.resposta ?? "(sem resposta)"}`).join("\n")}`
+      : "";
+    return [
+      antes,
+      `Pedido: ${p.texto}`,
+      `Componente ${c.id} ("${c.nome || "sem nome"}", ${c.categoria}, ${c.tecnologia}). Arquivo aberto no editor: ${p.arquivoAberto ?? "html"}.`,
+      `Código atual:\n<html>\n${c.html}\n</html>${c.tecnologia === "css" ? `\n<css>\n${c.css}\n</css>` : ""}`,
+      guia ?? "",
+      `Mude só o que o pedido pede. Se for conversa ou pergunta ("oi", "o que dá para fazer?"), só responda, sem gravar nada. Para mudar, grave com salvar_meu_componente (id ${c.id}), mandando o html e/ou o css inteiros; nome, descrição e tags só se o pedido falar deles. Se a pessoa pedir OUTRO componente (\"abre outro\", \"agora um toggle\"), crie com criar_meu_componente (nome, categoria, código) e ponha o link do editor na resposta. O que está aberto já fica salvo sozinho.`,
+    ].join("\n\n");
+  }
+  return [
+    `Pedido: ${p.texto}`,
+    `Projeto de vídeo ${p.projeto.id} ("${p.projeto.nome}").${p.clipeSelecionado ? ` Clipe selecionado: ${JSON.stringify(p.clipeSelecionado)}.` : ""}${p.cabecote != null ? ` Cabeçote em ${p.cabecote}s.` : ""}`,
+    `Leia com ver_projeto_video e edite com editar_projeto_video (operações pontuais).${local?.includes("gerar_voz") ? " Para narração, gere a fala com gerar_voz (neste computador) e ponha o asset que ela devolve no projeto." : ""}`,
+  ].join("\n\n");
+}
+
+const FERRAMENTAS = {
+  componente: ["ver_meu_componente", "salvar_meu_componente", "criar_meu_componente", "buscar_componentes", "ver_componente"],
+  video: ["ver_projeto_video", "editar_projeto_video", "salvar_projeto_video", "criar_projeto_video"],
+};
+
+/** Reads `claude -p --output-format stream-json` lines: text as it streams, tools in use, the session and the end. */
+export function lerEvento(linha, estado) {
+  let e;
+  try {
+    e = JSON.parse(linha);
+  } catch {
+    return;
+  }
+  if (e.session_id) estado.sessao = e.session_id;
+  if (e.type === "stream_event" && e.event?.type === "content_block_delta" && e.event.delta?.type === "text_delta") estado.texto += e.event.delta.text;
+  else if (e.type === "stream_event" && e.event?.type === "content_block_delta" && e.event.delta?.type === "thinking_delta")
+    estado.pensamento = (estado.pensamento ?? "") + e.event.delta.thinking;
+  else if (e.type === "stream_event" && e.event?.type === "content_block_start" && estado.texto && !estado.texto.endsWith("\n")) estado.texto += "\n";
+  else if (e.type === "assistant") {
+    for (const b of e.message?.content ?? [])
+      if (b.type === "tool_use") {
+        estado.ferramenta = String(b.name).replace(/^mcp__(ravox|local)__/, "");
+        estado.etapas = [...(estado.etapas ?? []).map((x) => ({ ...x, status: "feito" })), { texto: etapaDe(estado.ferramenta), status: "fazendo" }];
+        // The text before a tool call is Claude explaining what it will do: it goes to the "thinking" block.
+        if (estado.texto.trim()) estado.pensamento = `${estado.pensamento ?? ""}${estado.pensamento ? "\n\n" : ""}${estado.texto.trim()}`;
+        estado.texto = "";
+      }
+  } else if (e.type === "result") {
+    estado.fim = true;
+    estado.erro = e.is_error ? String(e.result ?? e.subtype ?? "erro") : null;
+    estado.final = typeof e.result === "string" ? e.result : estado.texto;
+  }
+}
+
+/** Each Ravox tool Claude uses becomes a step in the chat (the site is in Portuguese). */
+const ETAPA = {
+  ver_meu_componente: "Leu o componente",
+  salvar_meu_componente: "Gravou no editor",
+  criar_meu_componente: "Criou um componente novo",
+  buscar_componentes: "Buscou componentes na galeria",
+  ver_componente: "Olhou um componente da galeria",
+  ver_projeto_video: "Leu o projeto",
+  editar_projeto_video: "Editou a linha do tempo",
+  salvar_projeto_video: "Gravou a linha do tempo",
+  criar_projeto_video: "Criou um projeto",
+  gerar_voz: "Gravou uma narração",
+};
+export const etapaDe = (f) => ETAPA[f] ?? `Usou ${f}`;
+
+export function rodarClaude({ site, token, prompt, tipo, modelo, aoProgresso, local = null }) {
+  // Only the tools this request needs (the whole Ravox MCP made the safety filter flag even a "hi").
+  const url = `${site}/api/mcp?so=${FERRAMENTAS[tipo].join(",")}`;
+  // The computer's own tools (gerar_voz) only for video requests.
+  const locais = tipo === "video" && local?.ferramentas.length ? local.ferramentas : [];
+  const servidores = { ravox: { type: "http", url, headers: { Authorization: `Bearer ${token}` } } };
+  if (locais.length) servidores.local = { type: "http", url: `${local.base}/mcp` };
+  const mcp = JSON.stringify({ mcpServers: servidores });
+  const args = [
+    "-p",
+    prompt,
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    "--include-partial-messages",
+    "--mcp-config",
+    mcp,
+    "--strict-mcp-config",
+    // Lean run: none of the person's plugins, hooks, skills, CLAUDE.md or other settings (with them a one-line
+    // request carried ~200k tokens of context; without, ~3k). The subscription login still works.
+    "--setting-sources",
+    "",
+    "--disable-slash-commands",
+    "--tools",
+    "",
+    "--allowedTools",
+    ...FERRAMENTAS[tipo].map((f) => `mcp__ravox__${f}`),
+    ...locais.map((f) => `mcp__local__${f}`),
+    "--append-system-prompt",
+    SISTEMA,
+    ...(modelo ? ["--model", modelo] : []),
+  ];
+  const pasta = mkdtempSync(join(tmpdir(), "ravox-conector-"));
+  return new Promise((resolve) => {
+    const estado = { texto: "", ferramenta: null, sessao: null, fim: false, erro: null, final: "", etapas: [], pensamento: null };
+    const filho = spawn("claude", args, { cwd: pasta, stdio: ["ignore", "pipe", "pipe"], shell: process.platform === "win32" });
+    let resto = "";
+    let erroTexto = "";
+    const tique = setInterval(() => aoProgresso(estado), PROGRESSO);
+    filho.stdout.on("data", (b) => {
+      resto += b.toString();
+      const linhas = resto.split("\n");
+      resto = linhas.pop() ?? "";
+      for (const l of linhas) lerEvento(l, estado);
+    });
+    filho.stderr.on("data", (b) => (erroTexto += b.toString()));
+    filho.on("error", (e) => {
+      clearInterval(tique);
+      resolve({ ...estado, erro: e.message });
+    });
+    filho.on("close", (codigo) => {
+      clearInterval(tique);
+      if (resto) lerEvento(resto, estado);
+      if (!estado.fim) estado.erro = erroTexto.trim().split("\n").pop() || `claude saiu com código ${codigo}`;
+      resolve(estado);
+    });
+  });
+}
+
+/** Claude Code errors in words the chat can show (the site is in Portuguese). */
+export function explicarErro(erro) {
+  if (/safeguards flagged|usage policy/i.test(erro))
+    return "O filtro de segurança do Claude barrou este pedido (às vezes acontece por engano). Tente escrever de outro jeito.";
+  if (/rate limit|usage limit|limit reached|quota/i.test(erro)) return "Você chegou no limite de uso do Claude por agora. Tente de novo mais tarde.";
+  if (/not logged in|login|authenticate|\/login/i.test(erro)) return "O Claude Code deste computador não está logado. Rode claude no terminal e entre na sua conta.";
+  if (/overloaded|529|timeout|ECONN/i.test(erro)) return "O Claude está sobrecarregado agora. Tente de novo em instantes.";
+  return erro.slice(0, 600);
+}
+
+/* ---------------------------------------------------------------- the loop */
+
+const temClaude = () => new Promise((r) => execFile("claude", ["--version"], { shell: process.platform === "win32" }, (e) => r(!e)));
+const espera = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export async function conectar(opts) {
+  const site = (opts.site ?? process.env.RAVOX_SITE ?? process.env.RAVOX_REGISTRY ?? "https://ui.ravoxlabs.com").replace(/\/$/, "");
+  if (!(await temClaude())) throw new Error(t.semClaude);
+  let token = lerConfig()[site]?.token;
+  if (!token || opts.login) token = await entrar(site);
+
+  let tipos;
+  try {
+    tipos = await chamar(site, token, "tools/list");
+  } catch (e) {
+    if (!(e instanceof SemAcesso)) throw e;
+    console.log(t.sessaoVencida);
+    token = await entrar(site);
+    tipos = await chamar(site, token, "tools/list");
+  }
+  const filas = [["componente", "pedidos_componente", "responder_pedido_componente"], ["video", "pedidos_video", "responder_pedido_video"]].filter(([, f]) => tipos.includes(f));
+  const local = await servidorLocal(new URL(site).origin).catch(() => null);
+  console.log(t.ligado(site));
+
+  // Every request is a fresh, small session: the last exchanges of that component go in the prompt instead of
+  // resuming the session (a resumed one piles up every version of the code, costs more and trips the safety filter).
+  let parar = false;
+  let pausado = false;
+  process.once("SIGINT", () => {
+    parar = true;
+    console.log("");
+    process.exit(0);
+  });
+
+  while (!parar) {
+    try {
+      for (const [tipo, listar, responder] of filas) {
+        const r = await chamar(site, token, listar, { conector: true });
+        if (!!r.pausado !== pausado) {
+          pausado = !!r.pausado;
+          console.log(pausado ? t.pausado : t.retomado);
+        }
+        for (const p of r.pedidos.filter((x) => x.status === "pendente")) {
+          // Another connector (another window or computer) may have taken it first.
+          const assumiu = await chamar(site, token, responder, { id: p.id, status: "fazendo", assumir: true }).then(() => true, () => false);
+          if (!assumiu) continue;
+          console.log(t.pedido(p.texto));
+          let ultimo = "";
+          const aoProgresso = (e) => {
+            const dados = { resposta: e.texto.trim().slice(-1900), etapas: e.etapas, pensamento: (e.pensamento ?? "").slice(-7900) };
+            const chave = JSON.stringify(dados);
+            if (chave === ultimo) return;
+            ultimo = chave;
+            chamar(site, token, responder, { id: p.id, status: "fazendo", ...dados }).catch(() => {});
+          };
+          const rodar = () => rodarClaude({ site, token, prompt: montarPedido(tipo, p, r.guia, true, local?.ferramentas), tipo, modelo: opts.model ?? "sonnet", aoProgresso, local });
+          let fim = await rodar();
+          // The safety filter sometimes flags a normal request by mistake: one more try before giving up.
+          if (fim.erro && /safeguards flagged/i.test(fim.erro)) fim = await rodar();
+          const etapas = fim.etapas.map((x) => ({ ...x, status: "feito" }));
+          const pensamento = (fim.pensamento ?? "").slice(-7900);
+          if (fim.erro) {
+            console.log(t.erro(fim.erro));
+            await chamar(site, token, responder, { id: p.id, status: "erro", resposta: explicarErro(fim.erro), etapas, pensamento });
+          } else {
+            console.log(t.feito);
+            await chamar(site, token, responder, { id: p.id, status: "feito", resposta: (fim.final || fim.texto).trim().slice(0, 1990), etapas, pensamento });
+          }
+        }
+      }
+    } catch (e) {
+      // Revogada com o conector aberto = "Sair deste computador" no site: fecha (não abre o login sozinho).
+      if (e instanceof SemAcesso) {
+        console.log(t.saiu);
+        return 0;
+      }
+      console.log(t.falhaRede(e instanceof Error ? e.message : e));
+      await espera(INTERVALO * 3);
+    }
+    await espera(INTERVALO);
+  }
+  return 0;
+}

package/src/local.mjs

@@ -0,0 +1,293 @@
+// What the connector does on this computer: a tiny server on 127.0.0.1 that
+// - gives the Claude it runs an MCP tool that makes files here (gerar_voz: text → speech);
+// - lets the video editor (only the site's page) list, preview and generate voices and connect Azure;
+// - hands the generated files to the editor, which saves them in the browser (IndexedDB).
+// Nothing goes through the site. Voices: Microsoft's neural voices (Francisca, Antônio, Thalita). Without setup they
+// come from the Edge read-aloud service (`edge-tts`, free, light, no official license for ads); with an Azure key
+// (free tier F0, official, commercial use allowed; kept in ~/.config/ravox-ui/voz.json) the SAME voices come from
+// Azure, with nothing else changing. The macOS voices were dropped (robotic, and Apple's license is personal only).
+
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { createReadStream, existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const PASTA = join(homedir(), ".cache", "ravox-ui", "arquivos");
+const CONFIG = join(homedir(), ".config", "ravox-ui", "voz.json");
+export const PORTA = 47811;
+const EXEMPLO = "Oi! Esta é a minha voz. Fica assim na narração do seu vídeo.";
+const TIPOS = { mp3: "audio/mpeg" };
+
+const rodar = (cmd, args) =>
+  new Promise((ok, erro) => execFile(cmd, args, { timeout: 60000 }, (e, saida, err) => (e ? erro(new Error(String(err || e.message).trim().split("\n").pop())) : ok(saida))));
+
+/** The Edge voices in Brazilian Portuguese (the ones Azure also has, same names). */
+const EDGE = [
+  { voz: "pt-BR-FranciscaNeural", nome: "Francisca", genero: "feminina" },
+  { voz: "pt-BR-AntonioNeural", nome: "Antônio", genero: "masculina" },
+  { voz: "pt-BR-ThalitaMultilingualNeural", nome: "Thalita", genero: "feminina" },
+];
+
+/** How to run edge-tts here: installed, or through uv (`uvx` downloads it once, small). Null when neither. */
+let comandoEdge;
+const edgeTts = () =>
+  (comandoEdge ??= rodar("edge-tts", ["--help"]).then(
+    () => ["edge-tts"],
+    () => rodar("uvx", ["--version"]).then(() => ["uvx", "edge-tts"], () => null),
+  ));
+
+/* ---------------------------------------------------------------- config (Azure key) */
+
+function lerConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function gravarConfig(c) {
+  mkdirSync(dirname(CONFIG), { recursive: true });
+  writeFileSync(CONFIG, JSON.stringify(c, null, 2), { mode: 0o600 });
+}
+
+/* ---------------------------------------------------------------- voices */
+
+const escapar = (t) => t.replace(/[<>&'"]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", "'": "&apos;", '"': "&quot;" })[c]);
+
+let cacheAzure = null;
+/** Azure neural voices that speak Brazilian Portuguese (pt-BR ones first, then multilingual ones). */
+async function vozesAzure(conf = lerConfig().azure) {
+  if (!conf?.chave) return [];
+  if (cacheAzure?.chave === conf.chave) return cacheAzure.vozes;
+  const r = await fetch(`https://${conf.regiao}.tts.speech.microsoft.com/cognitiveservices/voices/list`, { headers: { "Ocp-Apim-Subscription-Key": conf.chave } });
+  if (r.status === 401 || r.status === 403) throw new Error("A chave da Azure foi recusada (confira a chave e a região).");
+  if (!r.ok) throw new Error(`A Azure respondeu ${r.status}.`);
+  const lista = await r.json();
+  const vozes = lista
+    .filter((v) => v.Locale === "pt-BR" || (v.SecondaryLocaleList ?? []).includes("pt-BR"))
+    .sort((a, b) => Number(b.Locale === "pt-BR") - Number(a.Locale === "pt-BR") || a.LocalName.localeCompare(b.LocalName))
+    .map((v) => ({
+      id: `azure:${v.ShortName}`,
+      nome: v.LocalName,
+      genero: v.Gender === "Female" ? "feminina" : v.Gender === "Male" ? "masculina" : null,
+      provedor: "azure",
+      descricao: v.Locale === "pt-BR" ? "Azure · pt-BR" : "Azure · multilíngue",
+    }));
+  cacheAzure = { chave: conf.chave, vozes };
+  return vozes;
+}
+
+export async function listarVozes() {
+  const conf = lerConfig().azure;
+  let azure = [];
+  let erroAzure = null;
+  try {
+    azure = await vozesAzure(conf);
+  } catch (e) {
+    erroAzure = e.message;
+  }
+  // Com a Azure ligada, as vozes vêm dela (oficial); sem, as mesmas vozes pelo Edge.
+  const edge = !azure.length && (await edgeTts()) ? EDGE.map((v) => ({ id: `edge:${v.voz}`, nome: v.nome, genero: v.genero, provedor: "edge", descricao: "Voz neural da Microsoft" })) : [];
+  return { azure: { ligado: !!conf?.chave, regiao: conf?.regiao ?? null, erro: erroAzure }, vozes: [...azure, ...edge] };
+}
+
+/** Saves the Azure key after checking it lists voices (so a typo shows up right away). */
+export async function ligarAzure({ chave, regiao }) {
+  chave = String(chave ?? "").trim();
+  regiao = String(regiao ?? "").trim().toLowerCase();
+  if (!/^[\w-]{16,128}$/.test(chave) || !/^[a-z0-9]{3,30}$/.test(regiao)) throw new Error("Chave ou região inválida.");
+  cacheAzure = null;
+  await vozesAzure({ chave, regiao });
+  gravarConfig({ ...lerConfig(), azure: { chave, regiao } });
+  return listarVozes();
+}
+export function desligarAzure() {
+  const c = lerConfig();
+  delete c.azure;
+  gravarConfig(c);
+  cacheAzure = null;
+}
+
+const padrao = async () => {
+  const { vozes } = await listarVozes();
+  return vozes[0]?.id ?? null;
+};
+
+/** Text → MP3 in the cache folder (Azure); returns the file name and the length (s). */
+export async function gerarVoz({ texto, voz, velocidade = 1 }) {
+  texto = String(texto ?? "").trim().slice(0, 3000);
+  if (!texto) throw new Error("texto vazio");
+  voz ||= await padrao();
+  if (!voz) throw new Error("Nenhuma voz ligada. Ligue a Azure no editor (aba Voz).");
+  const v = Math.min(1.6, Math.max(0.6, Number(velocidade) || 1));
+  mkdirSync(PASTA, { recursive: true });
+  const id = `voz-${randomBytes(5).toString("hex")}`;
+  let [provedor, nome] = [voz.slice(0, voz.indexOf(":")), voz.slice(voz.indexOf(":") + 1)];
+  const taxa = `${v >= 1 ? "+" : ""}${Math.round((v - 1) * 100)}%`;
+  // A mesma voz pelo caminho oficial quando a Azure está ligada.
+  if (provedor === "edge" && lerConfig().azure?.chave) provedor = "azure";
+
+  if (provedor === "edge") {
+    const cmd = await edgeTts();
+    if (!cmd) throw new Error("Para gerar voz, instale o uv (https://docs.astral.sh/uv) ou ligue a Azure na aba Voz.");
+    const arquivo = join(PASTA, `${id}.mp3`);
+    await rodar(cmd[0], [...cmd.slice(1), "--voice", nome, `--rate=${taxa}`, `--text=${texto}`, "--write-media", arquivo]).catch((e) => {
+      throw new Error(`Não deu para gerar a voz agora (${e.message.slice(0, 120)}). Tente de novo em instantes.`);
+    });
+    // MP3 de taxa constante (48 kbit/s): a duração sai do tamanho.
+    return { id, arquivo: `${id}.mp3`, duracao: Math.round(((statSync(arquivo).size * 8) / 48000) * 100) / 100 };
+  }
+
+  if (provedor === "azure") {
+    const conf = lerConfig().azure;
+    if (!conf?.chave) throw new Error("A Azure não está ligada neste computador (aba Voz do editor).");
+    const ssml = `<speak version="1.0" xml:lang="pt-BR"><voice name="${escapar(nome)}"><lang xml:lang="pt-BR"><prosody rate="${taxa}">${escapar(texto)}</prosody></lang></voice></speak>`;
+    const r = await fetch(`https://${conf.regiao}.tts.speech.microsoft.com/cognitiveservices/v1`, {
+      method: "POST",
+      headers: {
+        "Ocp-Apim-Subscription-Key": conf.chave,
+        "Content-Type": "application/ssml+xml",
+        "X-Microsoft-OutputFormat": "audio-48khz-192kbitrate-mono-mp3",
+        "User-Agent": "ravox-conector",
+      },
+      body: ssml,
+    });
+    if (r.status === 429) throw new Error("A Azure pediu para esperar um pouco (limite do plano grátis por minuto).");
+    if (!r.ok) throw new Error(`A Azure recusou (${r.status}). ${r.status === 401 ? "Confira a chave." : ""}`.trim());
+    const dados = Buffer.from(await r.arrayBuffer());
+    writeFileSync(join(PASTA, `${id}.mp3`), dados);
+    // MP3 de taxa constante (192 kbit/s): a duração sai do tamanho.
+    return { id, arquivo: `${id}.mp3`, duracao: Math.round(((dados.length * 8) / 192000) * 100) / 100 };
+  }
+
+  throw new Error(`Voz desconhecida: ${voz}`);
+}
+
+const resumo = (t) => (t.length > 40 ? `${t.slice(0, 40).trim()}…` : t);
+const assetDe = (v, texto, base) => ({ id: v.id, nome: `Voz: ${resumo(texto)}`, tipo: "audio", duracao: v.duracao, url: `${base}/arquivos/${v.arquivo}` });
+
+/* ---------------------------------------------------------------- MCP tools for Claude */
+
+async function ferramentasLocais() {
+  const { vozes } = await listarVozes();
+  // Sem a Azure ligada não há voz: o Claude avisa (pela descrição de ver_projeto_video) que é preciso ligar na aba Voz.
+  if (!vozes.length) return [];
+  return [
+    {
+      name: "gerar_voz",
+      description: `Gera narração em português do Brasil neste computador e devolve o asset pronto para o projeto de vídeo: ponha com editar_projeto_video { op: "asset", asset } e um clipe de áudio com a duração dele. Use a voz e a velocidade do projeto (campo voz) se houver; se a pessoa pedir voz feminina ou masculina, escolha pelo gênero (${vozes.map((v) => `${v.id} = ${v.nome}, ${v.genero}`).join("; ")}) e grave a escolha com { op: "voz" }. Uma fala por trecho (até ~2 frases).`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          texto: { type: "string", maxLength: 3000, description: "o que a voz fala" },
+          voz: { type: "string", enum: vozes.map((v) => v.id), description: `padrão ${vozes[0].id}` },
+          velocidade: { type: "number", minimum: 0.6, maximum: 1.6, description: "1 = normal; 0.9 mais calma; 1.15 mais rápida" },
+        },
+        required: ["texto"],
+      },
+      async executar(args, base) {
+        const v = await gerarVoz(args);
+        return { asset: assetDe(v, String(args.texto), base) };
+      },
+    },
+  ];
+}
+
+/* ---------------------------------------------------------------- the server */
+
+/** Starts the local server. `origem` = the site allowed to use it from the browser. */
+export async function servidorLocal(origem) {
+  let base = "";
+  const cors = { "access-control-allow-origin": origem, "access-control-allow-private-network": "true", vary: "origin" };
+  const json = (res, status, corpo, extra = {}) => res.writeHead(status, { "content-type": "application/json", ...extra }).end(JSON.stringify(corpo));
+  const lerCorpo = async (req) => {
+    let corpo = "";
+    for await (const b of req) {
+      corpo += b;
+      if (corpo.length > 20000) throw new Error("grande demais");
+    }
+    return corpo ? JSON.parse(corpo) : {};
+  };
+
+  async function mcp(req, res) {
+    let m;
+    try {
+      m = await lerCorpo(req);
+    } catch {
+      return json(res, 400, { jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } });
+    }
+    if (m.id === undefined) return res.writeHead(202).end();
+    const ok = (result) => json(res, 200, { jsonrpc: "2.0", id: m.id, result });
+    if (m.method === "initialize")
+      return ok({ protocolVersion: m.params?.protocolVersion ?? "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: "ravox-local", version: "2" } });
+    if (m.method === "ping") return ok({});
+    const ferramentas = await ferramentasLocais();
+    if (m.method === "tools/list") return ok({ tools: ferramentas.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+    if (m.method === "tools/call") {
+      const f = ferramentas.find((x) => x.name === m.params?.name);
+      if (!f) return json(res, 200, { jsonrpc: "2.0", id: m.id, error: { code: -32602, message: "ferramenta desconhecida" } });
+      try {
+        const saida = await f.executar(m.params.arguments ?? {}, base);
+        return ok({ content: [{ type: "text", text: JSON.stringify(saida) }], structuredContent: saida });
+      } catch (e) {
+        return ok({ content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }], isError: true });
+      }
+    }
+    return json(res, 200, { jsonrpc: "2.0", id: m.id, error: { code: -32601, message: "método desconhecido" } });
+  }
+
+  /** What the editor page uses (only from the site: the Origin is checked, not just CORS). */
+  async function editor(req, res, caminho) {
+    if (req.method === "OPTIONS") return res.writeHead(204, { ...cors, "access-control-allow-methods": "GET, POST, DELETE", "access-control-allow-headers": "content-type" }).end();
+    if (req.headers.origin !== origem) return res.writeHead(403).end();
+    try {
+      if (caminho === "/voz" && req.method === "GET") return json(res, 200, await listarVozes(), cors);
+      if (caminho === "/voz/azure" && req.method === "POST") return json(res, 200, await ligarAzure(await lerCorpo(req)), cors);
+      if (caminho === "/voz/azure" && req.method === "DELETE") {
+        desligarAzure();
+        return json(res, 200, await listarVozes(), cors);
+      }
+      if (caminho === "/voz/ouvir" && req.method === "POST") {
+        const corpo = await lerCorpo(req);
+        const v = await gerarVoz({ ...corpo, texto: corpo.texto || EXEMPLO });
+        const arquivo = join(PASTA, v.arquivo);
+        const dados = readFileSync(arquivo);
+        unlinkSync(arquivo);
+        return res.writeHead(200, { ...cors, "content-type": TIPOS[v.arquivo.split(".").pop()] }).end(dados);
+      }
+      if (caminho === "/voz/gerar" && req.method === "POST") {
+        const corpo = await lerCorpo(req);
+        const v = await gerarVoz(corpo);
+        return json(res, 200, { asset: assetDe(v, String(corpo.texto), base) }, cors);
+      }
+    } catch (e) {
+      return json(res, 400, { erro: e instanceof Error ? e.message : String(e) }, cors);
+    }
+    return res.writeHead(404, cors).end();
+  }
+
+  const servidor = createServer((req, res) => {
+    const u = new URL(req.url ?? "/", "http://127.0.0.1");
+    if (u.pathname.startsWith("/arquivos/")) {
+      if (req.method === "OPTIONS") return res.writeHead(204, { ...cors, "access-control-allow-methods": "GET" }).end();
+      const nome = u.pathname.slice("/arquivos/".length);
+      const caminho = join(PASTA, nome);
+      if (!/^[\w.-]+$/.test(nome) || !existsSync(caminho)) return res.writeHead(404, cors).end();
+      res.writeHead(200, { ...cors, "content-type": TIPOS[nome.split(".").pop()] ?? "application/octet-stream", "content-length": statSync(caminho).size });
+      return createReadStream(caminho).pipe(res);
+    }
+    if (u.pathname.startsWith("/voz")) return void editor(req, res, u.pathname);
+    // MCP only for local processes (Claude Code sends no Origin; a web page would).
+    if (u.pathname === "/mcp" && req.method === "POST" && !req.headers.origin) return void mcp(req, res);
+    res.writeHead(404).end();
+  });
+  await new Promise((ok) => {
+    servidor.once("error", () => servidor.listen(0, "127.0.0.1", ok));
+    servidor.listen(PORTA, "127.0.0.1", ok);
+  });
+  base = `http://127.0.0.1:${servidor.address().port}`;
+  // Always allowed: the tool only shows up for Claude when there is a voice (connecting Azure later just works).
+  return { base, ferramentas: ["gerar_voz"], fechar: () => servidor.close() };
+}

package/src/messages.mjs

@@ -10,13 +10,17 @@ Usage
   ravox add <name...>          add components or blocks (ravox add button dialog login-01)
   ravox add --all              add every component
   ravox list                   list components and blocks
+  ravox connect                answer the site editors' chat with your own Claude Code (keep it open)
 
 Options
   -f, --framework <name>       react, vue, svelte or angular (detected from package.json)
   -c, --cwd <dir>              project folder (default: current folder)
-  -o, --overwrite              overwrite existing files
+  -o, --overwrite              overwrite existing files and theme variables
   -y, --yes                    skip confirmation prompts
       --dry-run                show what would run, change nothing
+      --site <url>             site for connect (default: https://ui.ravoxlabs.com)
+      --login                  connect: sign in again
+      --model <name>           connect: Claude model (default: sonnet)
   -v, --version                print the version
 
 Docs: https://ui.ravoxlabs.com/en/ui`,
@@ -27,6 +31,8 @@ Docs: https://ui.ravoxlabs.com/en/ui`,
   blocksReactOnly: "Blocks are React only for now.",
   adding: (n, fw) => `Adding ${n} ${n === 1 ? "item" : "items"} to your ${fw} project…`,
   initReact: "Setting up the project and the Ravox theme…",
+  wroteConfig: (css) => `Created components.json (theme in ${css}).`,
+  keptVariables: (n) => `Kept ${n} CSS ${n === 1 ? "variable" : "variables"} you already had (only the missing ones were added; --overwrite takes the Ravox values).`,
   initOther: (fw) => `Adding the cn() helper and the Ravox theme to your ${fw} project…`,
   importTheme: 'Import the theme once in your main CSS, after Tailwind: @import "./ravox-tema.css";',
   needInit: "No components.json here yet: running ravox init first.",
@@ -48,13 +54,17 @@ Uso
   ravox add <nome...>          adiciona componentes ou blocos (ravox add button dialog login-01)
   ravox add --all              adiciona todos os componentes
   ravox list                   lista componentes e blocos
+  ravox conectar               responde o chat dos editores do site com o seu Claude Code (deixe aberto)
 
 Opções
   -f, --framework <nome>       react, vue, svelte ou angular (detectado pelo package.json)
   -c, --cwd <pasta>            pasta do projeto (padrão: a pasta atual)
-  -o, --overwrite              sobrescreve arquivos que já existem
+  -o, --overwrite              sobrescreve arquivos e variáveis do tema que já existem
   -y, --yes                    pula as confirmações
       --dry-run                mostra o que rodaria, sem mudar nada
+      --site <url>             site do conectar (padrão: https://ui.ravoxlabs.com)
+      --login                  conectar: entrar de novo
+      --model <nome>           conectar: modelo do Claude (padrão: sonnet)
   -v, --version                mostra a versão
 
 Documentação: https://ui.ravoxlabs.com/ui`,
@@ -65,6 +75,8 @@ Documentação: https://ui.ravoxlabs.com/ui`,
   blocksReactOnly: "Por enquanto os blocos são só para React.",
   adding: (n, fw) => `Adicionando ${n} ${n === 1 ? "item" : "itens"} ao seu projeto ${fw}…`,
   initReact: "Preparando o projeto e o tema do Ravox…",
+  wroteConfig: (css) => `components.json criado (tema em ${css}).`,
+  keptVariables: (n) => `${n === 1 ? "Mantive 1 variável" : `Mantive ${n} variáveis`} de CSS que você já tinha (só as que faltavam entraram; --overwrite usa os valores do Ravox).`,
   initOther: (fw) => `Adicionando a função cn() e o tema do Ravox ao seu projeto ${fw}…`,
   importTheme: 'Importe o tema uma vez no CSS principal, depois do Tailwind: @import "./ravox-tema.css";',
   needInit: "Ainda não há components.json aqui: rodando o ravox init antes.",

package/src/project.mjs

@@ -42,3 +42,53 @@ export function runnerFor(userAgent = "") {
 
 /** A React project already set up for shadcn (has components.json). */
 export const hasComponentsJson = (cwd) => existsSync(join(cwd, "components.json"));
+
+/** The main CSS file of a React project (where Tailwind is imported), relative to the project. */
+const CSS_FILES = [
+  "src/app/globals.css",
+  "app/globals.css",
+  "src/styles/globals.css",
+  "styles/globals.css",
+  "src/index.css",
+  "src/styles.css",
+  "src/app.css",
+  "app/app.css",
+  "resources/css/app.css",
+];
+
+/** The import alias from tsconfig paths ("@/*": ["./src/*"] → "@"), or null. Comments in tsconfig are fine. */
+export function aliasFrom(tsconfigText) {
+  const m = /"([^"*]+)\/\*"\s*:\s*\[\s*"(?:\.\/)?(?:src\/)?\*"/.exec(tsconfigText ?? "");
+  return m ? m[1] : null;
+}
+
+/**
+ * components.json for a React project with Tailwind 4, written by us instead of `shadcn init`: init always installs a
+ * base library (Radix, Base UI or React Aria) and the Ravox Kit uses none. Returns null when the project is not
+ * clear enough (no Tailwind 4, no CSS file, no alias): then `shadcn init` asks the user.
+ */
+export function reactConfig(cwd, pkg) {
+  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+  const tailwind = String(deps.tailwindcss ?? "");
+  if (!/^[\^~]?4/.test(tailwind) && !deps["@tailwindcss/vite"] && !deps["@tailwindcss/postcss"]) return null;
+  const css = CSS_FILES.find((f) => existsSync(join(cwd, f)));
+  if (!css) return null;
+  const tsconfig = ["tsconfig.json", "tsconfig.app.json"].map((f) => join(cwd, f)).filter((f) => existsSync(f));
+  const alias = tsconfig.map((f) => aliasFrom(readFileSync(f, "utf8"))).find(Boolean);
+  if (!alias) return null;
+  return {
+    $schema: "https://ui.shadcn.com/schema.json",
+    style: "new-york",
+    rsc: Boolean(deps.next),
+    tsx: tsconfig.length > 0,
+    tailwind: { config: "", css, baseColor: "neutral", cssVariables: true, prefix: "" },
+    iconLibrary: "lucide",
+    aliases: {
+      components: `${alias}/components`,
+      utils: `${alias}/lib/utils`,
+      ui: `${alias}/components/ui`,
+      lib: `${alias}/lib`,
+      hooks: `${alias}/hooks`,
+    },
+  };
+}

package/src/theme.mjs

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * The theme is installed by `shadcn add vault-tema.json`, which writes its CSS variables into the project's main CSS
+ * and replaces the ones with the same name. A project that already has its colors keeps them: after shadcn runs,
+ * every variable that existed before goes back to its old value, so only the missing ones are added.
+ */
+
+/** Every `--name: value` with the selector path it lives in (`@layer base > :root`), in order. */
+export function cssVariables(css) {
+  const found = [];
+  const stack = [];
+  let start = 0;
+  let i = 0;
+  while (i < css.length) {
+    const ch = css[i];
+    if (ch === "/" && css[i + 1] === "*") {
+      const end = css.indexOf("*/", i + 2);
+      i = end < 0 ? css.length : end + 2;
+      start = i;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      const end = css.indexOf(ch, i + 1);
+      i = end < 0 ? css.length : end + 1;
+      continue;
+    }
+    if (ch === "{") {
+      stack.push(css.slice(start, i).trim().replace(/\s+/g, " "));
+      start = i + 1;
+    } else if (ch === "}" || ch === ";") {
+      const decl = css.slice(start, i);
+      const m = /^(\s*)(--[\w-]+)(\s*:\s*)([\s\S]*?)\s*$/.exec(decl);
+      if (m) {
+        const valueStart = start + m[1].length + m[2].length + m[3].length;
+        found.push({ path: stack.join(" > "), name: m[2], value: m[4], start: valueStart, end: valueStart + m[4].length });
+      }
+      if (ch === "}") stack.pop();
+      start = i + 1;
+    }
+    i++;
+  }
+  return found;
+}
+
+/** `after` with the variables that already existed in `before` (same block, same name) back to their old value. */
+export function keepExistingVariables(before, after) {
+  const old = new Map(cssVariables(before).map((v) => [`${v.path}|${v.name}`, v.value]));
+  let css = after;
+  let kept = 0;
+  for (const v of cssVariables(after).reverse()) {
+    const previous = old.get(`${v.path}|${v.name}`);
+    if (previous === undefined || previous === v.value) continue;
+    css = css.slice(0, v.start) + previous + css.slice(v.end);
+    kept++;
+  }
+  return { css, kept };
+}
+
+/** The main CSS file named in components.json, if it exists. */
+export function mainCss(cwd) {
+  try {
+    const css = JSON.parse(readFileSync(join(cwd, "components.json"), "utf8"))?.tailwind?.css;
+    return css && existsSync(join(cwd, css)) ? join(cwd, css) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Runs `install` (which writes the theme) and then restores the variables the project already had. */
+export async function keepTheme(cwd, install) {
+  const file = mainCss(cwd);
+  const before = file ? readFileSync(file, "utf8") : null;
+  const code = await install();
+  if (!file || before === null || !existsSync(file)) return { code, kept: 0 };
+  const { css, kept } = keepExistingVariables(before, readFileSync(file, "utf8"));
+  if (kept) writeFileSync(file, css);
+  return { code, kept };
+}