@ravox-ui/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @ravox-ui/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.
+Add [Ravox Kit](https://ui.ravoxlabs.com/en/ui) components, blocks and themes to your project. Works with React, Vue, Svelte and Angular.
+
+```bash
+npx @ravox-ui/cli init                 # set up the project (config, cn() helper and the Ravox theme)
+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
+```
+
+Also with `pnpm dlx @ravox-ui/cli …`, `yarn dlx @ravox-ui/cli …` and `bunx @ravox-ui/cli …`.
+Installed globally (`npm i -g @ravox-ui/cli`), the command is just `ravox`.
+
+## How it works
+
+The code is copied into your project, so it is yours to edit: there is no runtime package to keep updated.
+Under the hood it uses the [shadcn](https://ui.shadcn.com) CLI with the Ravox registry
+(`https://ui.ravoxlabs.com/r`), so it plays well with other shadcn components in the same project.
+
+- **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.
+- **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.
+
+## Options
+
+| Option | |
+| --- | --- |
+| `-f, --framework <name>` | `react`, `vue`, `svelte` or `angular` |
+| `-c, --cwd <dir>` | project folder (default: current folder) |
+| `-o, --overwrite` | overwrite existing files |
+| `-y, --yes` | skip confirmation prompts |
+| `--dry-run` | print the shadcn command, change nothing |
+
+Messages are in Portuguese when your system language is Portuguese (`LANG=pt_BR…`).
+
+## Links
+
+- Components and docs: https://ui.ravoxlabs.com/en/ui
+- Blocks: https://ui.ravoxlabs.com/en/ui/blocks
+- Use it from your AI agent (MCP): https://ui.ravoxlabs.com/mcp
+
+MIT © Ravox Labs

package/bin/ravox.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.mjs";
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  },
+);

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@ravox-ui/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Add Ravox Kit components, blocks and themes to your project (React, Vue, Svelte and Angular).",
+  "type": "module",
+  "bin": {
+    "ravox": "bin/ravox.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "keywords": [
+    "ravox",
+    "ui",
+    "components",
+    "shadcn",
+    "react",
+    "vue",
+    "svelte",
+    "angular",
+    "tailwind",
+    "cli"
+  ],
+  "homepage": "https://ui.ravoxlabs.com/en/ui",
+  "license": "MIT",
+  "author": "Ravox Labs"
+}

package/src/cli.mjs

@@ -0,0 +1,133 @@
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { messages } from "./messages.mjs";
+import { detectFramework, FRAMEWORKS, hasComponentsJson, readPackageJson, runnerFor } from "./project.mjs";
+import { availableNames, fetchIndex, itemUrl, resolveNames, setupUrls } from "./registry.mjs";
+import { suggest } from "./suggest.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 };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const value = () => {
+      const v = argv[++i];
+      if (v === undefined) throw new Error(`${a} needs a value`);
+      return v;
+    };
+    if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "-v" || a === "--version") opts.version = true;
+    else if (a === "-f" || a === "--framework") opts.framework = value().toLowerCase();
+    else if (a.startsWith("--framework=")) opts.framework = a.slice(12).toLowerCase();
+    else if (a === "-c" || a === "--cwd") opts.cwd = resolve(value());
+    else if (a === "-o" || a === "--overwrite") opts.overwrite = true;
+    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 (!opts.command) opts.command = a;
+    else opts.names.push(a);
+  }
+  return opts;
+}
+
+/** Runs shadcn with the user's package manager, streaming its output (prompts included). */
+function run(cmd, opts, t) {
+  if (opts.dryRun) {
+    console.log(`${t.dryRun} ${cmd.join(" ")}`);
+    return Promise.resolve(0);
+  }
+  return new Promise((done) => {
+    const child = spawn(cmd[0], cmd.slice(1), { cwd: opts.cwd, stdio: "inherit", shell: process.platform === "win32" });
+    child.on("close", (code) => done(code ?? 1));
+    child.on("error", (e) => {
+      console.error(e.message);
+      done(1);
+    });
+  });
+}
+
+function shadcn(args, opts) {
+  const flags = [...(opts.yes ? ["--yes"] : []), ...(opts.overwrite && args[0] === "add" ? ["--overwrite"] : []), "--cwd", opts.cwd];
+  return [...runnerFor(process.env.npm_config_user_agent), "shadcn@latest", ...args, ...flags];
+}
+
+function frameworkOf(opts, t) {
+  const fw = opts.framework ?? detectFramework(readPackageJson(opts.cwd));
+  if (!fw) throw new Error(t.noFramework);
+  if (!FRAMEWORKS.includes(fw)) throw new Error(t.badFramework(fw));
+  return fw;
+}
+
+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);
+  }
+  console.log(t.initOther(fw));
+  const code = await run(shadcn(["add", ...setupUrls(fw)], opts, t), opts, t);
+  if (code === 0) console.log(t.importTheme);
+  return code;
+}
+
+async function add(opts, t) {
+  const fw = frameworkOf(opts, t);
+  const index = await fetchIndex();
+  const available = availableNames(index, fw);
+  const names = opts.all ? index.components.map((c) => c.name).filter((n) => available.includes(n)) : opts.names;
+  if (!names.length) throw new Error(t.nothingToAdd);
+
+  const { known, unknown } = resolveNames(names, available, index.aliases);
+  if (unknown.length) {
+    const blocks = index.blocks.map((b) => b.name);
+    for (const u of unknown) console.error(fw !== "react" && blocks.includes(u.toLowerCase()) ? t.blocksReactOnly : t.unknown(u, suggest(u, available)));
+    return 1;
+  }
+
+  if (fw === "react" && !hasComponentsJson(opts.cwd)) {
+    console.log(t.needInit);
+    const code = await init(opts, t);
+    if (code !== 0) return code;
+  }
+  console.log(t.adding(known.length, fw));
+  // Non-React items are universal (fixed targets), so they also bring cn() and the theme the first time.
+  const urls = [...(fw === "react" ? [] : setupUrls(fw)), ...known.map((n) => itemUrl(n, fw))];
+  const code = await run(shadcn(["add", ...urls], opts, t), opts, t);
+  if (code === 0) console.log(t.done);
+  return code;
+}
+
+async function list(opts, t) {
+  const index = await fetchIndex();
+  const fw = opts.framework ?? detectFramework(readPackageJson(opts.cwd)) ?? "react";
+  const width = Math.max(...index.components.map((c) => c.name.length)) + 2;
+  console.log(`\n${t.components}`);
+  for (const c of index.components) console.log(`  ${c.name.padEnd(width)}${c.title}`);
+  console.log(`\n${t.blocks}`);
+  for (const b of index.blocks) console.log(`  ${b.name.padEnd(width)}${b.title}`);
+  console.log(`\n${t.available(fw, availableNames(index, fw).filter((n) => !index.blocks.some((b) => b.name === n)).length)}`);
+  return 0;
+}
+
+export async function main(argv) {
+  const t = messages();
+  const opts = parseArgs(argv);
+  if (opts.version) {
+    console.log(VERSION);
+    return 0;
+  }
+  if (opts.help || !opts.command) {
+    console.log(t.help);
+    return 0;
+  }
+  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);
+  console.error(t.unknownCommand(opts.command));
+  return 1;
+}

package/src/messages.mjs

@@ -0,0 +1,83 @@
+// Terminal messages in English, or Portuguese when the system language is Portuguese (LANG=pt_BR...).
+
+const en = {
+  help: `ravox: add Ravox Kit components to your project (React, Vue, Svelte and Angular)
+
+Run it with npx @ravox-ui/cli <command> (or npm i -g @ravox-ui/cli, then just ravox <command>)
+
+Usage
+  ravox init                   set up the project (config, cn() helper and the Ravox theme)
+  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
+
+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
+  -y, --yes                    skip confirmation prompts
+      --dry-run                show what would run, change nothing
+  -v, --version                print the version
+
+Docs: https://ui.ravoxlabs.com/en/ui`,
+  noFramework: "Could not tell the framework from package.json. Pass --framework react|vue|svelte|angular.",
+  badFramework: (f) => `Unknown framework "${f}". Use react, vue, svelte or angular.`,
+  nothingToAdd: "Tell me what to add: npx @ravox-ui/cli add button (or add --all). See them all with: npx @ravox-ui/cli list",
+  unknown: (name, hint) => `"${name}" is not in the Ravox Kit.${hint ? ` Did you mean "${hint}"?` : ""}`,
+  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…",
+  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.",
+  done: "Done.",
+  dryRun: "Would run:",
+  components: "Components",
+  blocks: "Blocks (React)",
+  available: (fw, n) => `${n} components available for ${fw}.`,
+  unknownCommand: (c) => `Unknown command "${c}". Run npx @ravox-ui/cli --help.`,
+};
+
+const pt = {
+  help: `ravox: adicione componentes do Ravox Kit ao seu projeto (React, Vue, Svelte e Angular)
+
+Rode com npx @ravox-ui/cli <comando> (ou npm i -g @ravox-ui/cli e depois só ravox <comando>)
+
+Uso
+  ravox init                   prepara o projeto (configuração, função cn() e o tema do Ravox)
+  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
+
+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
+  -y, --yes                    pula as confirmações
+      --dry-run                mostra o que rodaria, sem mudar nada
+  -v, --version                mostra a versão
+
+Documentação: https://ui.ravoxlabs.com/ui`,
+  noFramework: "Não deu para saber o framework pelo package.json. Passe --framework react|vue|svelte|angular.",
+  badFramework: (f) => `Framework "${f}" desconhecido. Use react, vue, svelte ou angular.`,
+  nothingToAdd: "Diga o que adicionar: npx @ravox-ui/cli add button (ou add --all). Veja todos com: npx @ravox-ui/cli list",
+  unknown: (name, hint) => `"${name}" não existe no Ravox Kit.${hint ? ` Você quis dizer "${hint}"?` : ""}`,
+  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…",
+  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.",
+  done: "Pronto.",
+  dryRun: "Rodaria:",
+  components: "Componentes",
+  blocks: "Blocos (React)",
+  available: (fw, n) => `${n} componentes disponíveis para ${fw}.`,
+  unknownCommand: (c) => `Comando "${c}" desconhecido. Rode npx @ravox-ui/cli --help.`,
+};
+
+/** Portuguese when the system says so, English otherwise. */
+export function messages(env = process.env) {
+  const lang = (env.RAVOX_LANG ?? env.LC_ALL ?? env.LC_MESSAGES ?? env.LANG ?? "").toLowerCase();
+  return lang.startsWith("pt") ? pt : en;
+}

package/src/project.mjs

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const FRAMEWORKS = ["react", "vue", "svelte", "angular"];
+
+/** Reads package.json from the project folder (null when there is none). */
+export function readPackageJson(cwd) {
+  const file = join(cwd, "package.json");
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Which framework the project uses, from its dependencies. Angular and Svelte win over Vue/React (they may ship both). */
+export function detectFramework(pkg) {
+  if (!pkg) return null;
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies };
+  if (deps["@angular/core"]) return "angular";
+  if (deps.svelte || deps["@sveltejs/kit"]) return "svelte";
+  if (deps.vue || deps.nuxt) return "vue";
+  if (deps.react || deps.next) return "react";
+  return null;
+}
+
+/**
+ * How to run shadcn with the same package manager the user called us with (npx, pnpm dlx, yarn dlx, bunx).
+ * Yarn 1 has no `dlx`, so it falls back to npx.
+ */
+export function runnerFor(userAgent = "") {
+  const ua = userAgent.toLowerCase();
+  if (ua.startsWith("pnpm/")) return ["pnpm", "dlx"];
+  if (ua.startsWith("bun/")) return ["bunx"];
+  if (ua.startsWith("yarn/")) {
+    const major = Number(ua.slice(5).split(".")[0]);
+    return major >= 2 ? ["yarn", "dlx"] : ["npx", "--yes"];
+  }
+  return ["npx", "--yes"];
+}
+
+/** A React project already set up for shadcn (has components.json). */
+export const hasComponentsJson = (cwd) => existsSync(join(cwd, "components.json"));

package/src/registry.mjs

@@ -0,0 +1,48 @@
+// Where Ravox Kit items live. RAVOX_REGISTRY points somewhere else (e.g. http://localhost:3200) for local testing.
+export const BASE = (process.env.RAVOX_REGISTRY ?? "https://ui.ravoxlabs.com").replace(/\/$/, "");
+
+/** The index of everything that exists (components, blocks and which framework ports are ready). */
+export async function fetchIndex(fetchImpl = fetch) {
+  let res;
+  try {
+    res = await fetchImpl(`${BASE}/r/ravox.json`);
+  } catch {
+    throw new Error(`Could not reach ${BASE}. Check your connection and try again.`);
+  }
+  if (!res.ok) throw new Error(`Could not read the Ravox index (${res.status} at ${BASE}/r/ravox.json).`);
+  return res.json();
+}
+
+/** Item URL for a framework: React uses the shadcn item, the others the universal items under r/<framework>/. */
+export function itemUrl(name, framework) {
+  return framework === "react" ? `${BASE}/r/${name}.json` : `${BASE}/r/${framework}/${name}.json`;
+}
+
+/** The theme (and the cn() helper for non-React projects) that every component reads. */
+export function setupUrls(framework) {
+  return framework === "react" ? [`${BASE}/r/vault-tema.json`] : [`${BASE}/r/${framework}/utils.json`, `${BASE}/r/${framework}/tema.json`];
+}
+
+/** Names available for a framework: every component, plus blocks (React only). */
+export function availableNames(index, framework) {
+  if (framework === "react") return [...index.components.map((c) => c.name), ...index.blocks.map((b) => b.name)];
+  return index.frameworks?.[framework] ?? [];
+}
+
+/**
+ * Splits what the user asked for into known names and unknown ones. Accepts "Button", "button", "button.json" and
+ * the old Portuguese names (`aliases`, e.g. "botao" -> "button").
+ */
+export function resolveNames(requested, available, aliases = {}) {
+  const known = [];
+  const unknown = [];
+  for (const raw of requested) {
+    const typed = raw.trim().toLowerCase().replace(/\.json$/, "").replace(/\s+/g, "-");
+    const name = aliases[typed] ?? typed;
+    if (!name) continue;
+    if (available.includes(name)) {
+      if (!known.includes(name)) known.push(name);
+    } else unknown.push(raw);
+  }
+  return { known, unknown };
+}

package/src/suggest.mjs

@@ -0,0 +1,30 @@
+/** Edit distance between two words (how many letters to add, remove or change). */
+export function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const temp = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = temp;
+    }
+  }
+  return row[b.length];
+}
+
+/** The closest available name, when it is close enough to be a typo (or a prefix like "dropdown"). */
+export function suggest(name, available) {
+  const word = name.toLowerCase();
+  const prefix = available.find((a) => a.startsWith(word) || a.split("-").includes(word));
+  if (prefix) return prefix;
+  let best = null;
+  let bestDistance = Infinity;
+  for (const a of available) {
+    // Also compare with the start of longer names ("dropdwn" is close to "dropdown-menu").
+    const start = Math.min(distance(word, a.slice(0, word.length)), distance(word, a.slice(0, word.length + 1)));
+    const d = Math.min(distance(word, a), start + 1);
+    if (d < bestDistance) [best, bestDistance] = [a, d];
+  }
+  return bestDistance <= Math.max(2, Math.floor(word.length / 3)) ? best : null;
+}