@promovaweb/brandfy 1.1.0 → 1.3.1

package/README.md

@@ -1,9 +1,8 @@
 # CLI do Brandfy
 
-O pacote `@promovaweb/brandfy` instala as skills oficiais e oferece atalhos
-para preparar, conferir e compilar a marca de um projeto. O executável usa o
-pacote `skills` como dependência fixa, portanto a instalação e a atualização
-continuam compatíveis com `skills-lock.json`.
+O pacote `@promovaweb/brandfy` instala e mantém o sistema de skills no projeto
+consumidor. A conversa sobre a marca acontece exclusivamente na skill
+`$brandfy`; o CLI não expõe atalhos para especialistas, geradores ou auditorias.
 
 ## Instalação
 
@@ -11,57 +10,43 @@ Instale o executável globalmente:
 
 ```bash
 npm install --global @promovaweb/brandfy
-brandfy init .
+brandfy install .
 ```
 
-Também é possível executar sem instalação global:
+O comando instala o catálogo completo pelo gerenciador `skills`, prepara
+`.brandfy/`, cria ou confere `BRAND.md`, mantém `brand/README.md` como índice e
+atualiza o bloco gerenciado do `AGENTS.md`.
 
-```bash
-npx @promovaweb/brandfy init .
-```
-
-O comando `init` instala todas as skills no projeto, prepara `.brandfy/`,
-cria a estrutura inicial em `brand/` e inclui o bloco gerenciado no
-`AGENTS.md`.
-
-## Comandos
+## Comandos públicos
 
 | Comando | Resultado |
 | --- | --- |
-| `brandfy init [diretório]` | Instala as skills e executa o setup. |
-| `brandfy doctor [diretório]` | Confere Node.js, skills, lock, configuração, manual e instruções. |
-| `brandfy skills list` | Lista o catálogo disponível na origem configurada. |
-| `brandfy skills install [diretório]` | Instala todas as skills pelo `skills add`. |
-| `brandfy skills update [diretório]` | Reinstala somente as skills do Brandfy a partir da origem. |
-| `brandfy pdf [diretório]` | Compila `brand/README.md` em `brand/brand-guide.pdf`. |
-| `brandfy audit [diretório]` | Executa a auditoria e atualiza `.brandfy/audit.md`. |
-| `brandfy update [diretório]` | Atualiza as skills e executa o setup em modo de conferência. |
-
-Use `--source <origem>` para testar um checkout local ou outra origem aceita
-pelo gerenciador. O destino padrão é `promovaweb/brandfy`, e o agente padrão é
-o Codex.
-
-Os argumentos escritos depois de `--` seguem para o script da skill. Este
-exemplo escolhe outro nome para o PDF:
+| `brandfy install .` | Instala todas as skills e prepara o projeto consumidor. |
+| `brandfy update` | Atualiza as skills, reconcilia a estrutura e confere o setup. |
+| `brandfy doctor` | Diagnostica Node.js, as 19 skills, lock, configuração e arquivos da marca. |
 
-```bash
-brandfy pdf . -- --output brand/manual-da-marca.pdf
-```
+O diretório usado por `update` e `doctor` é o projeto atual. Para instalar em
+outro local, informe esse caminho somente no comando `install`, como em
+`brandfy install ../meu-projeto`.
+
+Depois de `brandfy install .`, abra o agente e use apenas `$brandfy`. A skill
+orquestradora chama `brandfy-setup`, `brandfy-mvp` e as demais especialistas na
+ordem adequada.
 
 ## Atualizações
 
 O framework e o CLI compartilham a mesma SemVer. Atualize o executável pelo npm
-e, dentro do projeto, atualize as skills:
+e, dentro do projeto, execute:
 
 ```bash
 npm install --global @promovaweb/brandfy@latest
-brandfy update .
-brandfy doctor .
+brandfy update
+brandfy doctor
 ```
 
-O comando `brandfy update` não substitui arquivos da marca que pertencem ao
-usuário. O setup executado na sequência confere a estrutura e informa qualquer
-arquivo ausente.
+O `brandfy update` preserva arquivos autorais e reaplica somente a estrutura
+gerenciada. O diagnóstico retorna código diferente de zero quando faltar uma
+skill, configuração, arquivo da marca ou bloco de instruções.
 
 ## Desenvolvimento
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promovaweb/brandfy",
-  "version": "1.1.0",
+  "version": "1.3.1",
   "description": "CLI do Brandfy para instalar skills e manter sistemas de marca em projetos com agentes.",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -1,18 +1,15 @@
 /**
- * Implementa a interface de linha de comando do Brandfy.
+ * Implementa a interface pública mínima do CLI do Brandfy.
  *
- * O CLI delega instalação e atualização ao pacote `skills`. Os comandos de
- * geração executam os scripts das skills instaladas no projeto consumidor.
+ * A conversa de marca acontece na skill `$brandfy`. O CLI somente instala,
+ * atualiza e diagnostica o sistema no projeto consumidor.
  */
 
 import path from "node:path";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { createProcessRunner } from "./process-runner.mjs";
-import {
-  inspectProject,
-  locateSkillScript,
-} from "./project.mjs";
+import { inspectProject, locateSkillScript } from "./project.mjs";
 
 const packageRoot = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -27,50 +24,27 @@ export const DEFAULT_AGENT = "codex";
 
 const HELP = `Brandfy ${packageManifest.version}
 
-Instala as skills do Brandfy e executa os geradores no projeto atual.
+Instala e mantém o sistema de skills do Brandfy no projeto atual.
 
-Uso:
-  brandfy init [diretório]              Instala as skills e prepara a marca
-  brandfy doctor [diretório] [--json]   Confere a instalação e os arquivos
-  brandfy skills list                   Lista as skills disponíveis
-  brandfy skills install [diretório]    Instala todas as skills
-  brandfy skills update [diretório]     Atualiza somente as skills do Brandfy
-  brandfy pdf [diretório] [-- ...]      Compila brand/README.md em PDF
-  brandfy audit [diretório] [-- ...]    Audita a estrutura da marca
-  brandfy update [diretório]            Atualiza as skills e confere o setup
-  brandfy --version                     Mostra a versão do CLI
+Comandos:
+  brandfy install .       Instala as skills e prepara o projeto
+  brandfy update           Atualiza as skills e reconcilia o projeto
+  brandfy doctor           Diagnostica skills e arquivos
+  brandfy --version        Mostra a versão do CLI
 
 Opções:
-  --source <origem>   Repositório ou caminho aceito pelo skills add
-  --agent <agente>    Agente de destino (padrão: codex)
-  --json              Emite o diagnóstico como JSON
-  --help              Mostra esta ajuda
+  --json                   Emite o diagnóstico em JSON
+  --help                   Mostra esta ajuda
 
-Os argumentos escritos depois de -- seguem para o gerador de PDF ou auditoria.
+Depois da instalação, converse somente com a skill $brandfy.
 `;
 
 function parseArguments(argv) {
   const positional = [];
-  const passthrough = [];
-  const options = {
-    source: DEFAULT_SOURCE,
-    agent: DEFAULT_AGENT,
-    json: false,
-  };
-  let forwarding = false;
-
-  for (let index = 0; index < argv.length; index += 1) {
-    const argument = argv[index];
-    if (forwarding) {
-      passthrough.push(argument);
-    } else if (argument === "--") {
-      forwarding = true;
-    } else if (argument === "--source" || argument === "--agent") {
-      const value = argv[index + 1];
-      if (!value) throw new Error(`${argument} exige um valor.`);
-      options[argument.slice(2)] = value;
-      index += 1;
-    } else if (argument === "--json") {
+  const options = { json: false };
+
+  for (const argument of argv) {
+    if (argument === "--json") {
       options.json = true;
     } else if (argument.startsWith("-")) {
       throw new Error(`Opção desconhecida: ${argument}`);
@@ -79,7 +53,7 @@ function parseArguments(argv) {
     }
   }
 
-  return { positional, passthrough, options };
+  return { positional, options };
 }
 
 function projectFrom(value, cwd) {
@@ -93,13 +67,13 @@ async function ensureSuccess(result, action) {
   }
 }
 
-async function installSkills(runner, project, options, label) {
+async function installSkills(runner, project, label) {
   console.log(`${label} as skills do Brandfy em ${project}...`);
   const result = await runner.runSkills([
     "add",
-    options.source,
+    DEFAULT_SOURCE,
     "--agent",
-    options.agent,
+    DEFAULT_AGENT,
     "--skill",
     "*",
     "-y",
@@ -108,25 +82,31 @@ async function installSkills(runner, project, options, label) {
   await ensureSuccess(result, "O gerenciador skills não concluiu a instalação");
 }
 
-async function runInstalledScript(
-  runner,
-  project,
-  skill,
-  relativeScript,
-  args,
-) {
-  const script = await locateSkillScript(project, skill, relativeScript);
+async function runSetup(runner, project, check = false) {
+  const script = await locateSkillScript(
+    project,
+    "brandfy-setup",
+    "scripts/setup.mjs",
+  );
   if (!script) {
     throw new Error(
-      `A skill ${skill} não está instalada. Execute brandfy init primeiro.`,
+      "A skill brandfy-setup não está instalada. Execute brandfy install . primeiro.",
     );
   }
+  const args = ["--project", project];
+  if (check) args.push("--check");
   const result = await runner.runScript(script, args, project);
-  await ensureSuccess(result, `O script da skill ${skill} falhou`);
+  await ensureSuccess(result, "O brandfy-setup não concluiu a operação");
+}
+
+function assertCommandShape(positional) {
+  if (positional.length > 2) {
+    throw new Error("Use somente um comando e, opcionalmente, o diretório do projeto.");
+  }
 }
 
 /**
- * Executa um comando com dependências injetáveis para permitir testes isolados.
+ * Executa a interface pública com dependências injetáveis para testes.
  *
  * @param {string[]} argv Argumentos sem `node` e sem o nome do binário.
  * @param {{cwd?: string, runner?: object, stdout?: Function}} dependencies
@@ -142,100 +122,53 @@ export async function execute(argv, dependencies = {}) {
     stdout(HELP.trimEnd());
     return 0;
   }
-  if (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version") {
+  if (argv[0] === "--version" || argv[0] === "-v") {
     stdout(packageManifest.version);
     return 0;
   }
 
-  const { positional, passthrough, options } = parseArguments(argv);
-  const [command, subcommand, possibleProject] = positional;
-
-  if (command === "skills" && subcommand === "list") {
-    const result = await runner.runSkills(
-      ["add", options.source, "--list"],
-      cwd,
-    );
-    await ensureSuccess(result, "Não foi possível listar as skills");
-    return 0;
-  }
-
-  if (
-    command === "skills"
-    && (subcommand === "install" || subcommand === "update")
-  ) {
-    const project = projectFrom(possibleProject, cwd);
-    await installSkills(
-      runner,
-      project,
-      options,
-      subcommand === "install" ? "Instalando" : "Atualizando",
-    );
-    return 0;
-  }
-
-  const project = projectFrom(subcommand, cwd);
-  if (command === "init") {
-    await installSkills(runner, project, options, "Instalando");
-    await runInstalledScript(
-      runner,
-      project,
-      "brandfy-setup",
-      "scripts/setup.mjs",
-      ["--project", project],
-    );
-    stdout(`Brandfy preparado em ${project}.`);
-    return 0;
-  }
+  const { positional, options } = parseArguments(argv);
+  const [command, possibleProject] = positional;
+  assertCommandShape(positional);
 
-  if (command === "doctor") {
-    const checks = await inspectProject(project);
-    if (options.json) {
-      stdout(JSON.stringify({ project, checks }, null, 2));
-    } else {
-      stdout(`Diagnóstico do Brandfy em ${project}`);
-      for (const check of checks) {
-        stdout(`${check.ok ? "✓" : "✗"} ${check.name}: ${check.detail}`);
-      }
-    }
-    return checks.every((check) => check.ok) ? 0 : 1;
+  if (![
+    "install",
+    "update",
+    "doctor",
+  ].includes(command)) {
+    throw new Error(`Comando desconhecido: ${command || "(vazio)"}`);
   }
 
-  if (command === "pdf") {
-    await runInstalledScript(
-      runner,
-      project,
-      "brandfy-guia-pdf",
-      "scripts/build-brand-guide.mjs",
-      ["--project", project, ...passthrough],
-    );
-    return 0;
+  const project = projectFrom(possibleProject, cwd);
+  if (options.json && command !== "doctor") {
+    throw new Error("A opção --json só pode ser usada com brandfy doctor.");
   }
 
-  if (command === "audit") {
-    await runInstalledScript(
-      runner,
-      project,
-      "brandfy-auditoria",
-      "scripts/audit-brand.mjs",
-      ["--project", project, ...passthrough],
-    );
+  if (command === "install") {
+    await installSkills(runner, project, "Instalando");
+    await runSetup(runner, project);
+    stdout(`Brandfy instalado e preparado em ${project}.`);
     return 0;
   }
 
   if (command === "update") {
-    await installSkills(runner, project, options, "Atualizando");
-    await runInstalledScript(
-      runner,
-      project,
-      "brandfy-setup",
-      "scripts/setup.mjs",
-      ["--project", project, "--check"],
-    );
-    stdout(`Skills atualizadas e setup conferido em ${project}.`);
+    await installSkills(runner, project, "Atualizando");
+    await runSetup(runner, project);
+    await runSetup(runner, project, true);
+    stdout(`Brandfy atualizado e conferido em ${project}.`);
     return 0;
   }
 
-  throw new Error(`Comando desconhecido: ${command || "(vazio)"}`);
+  const checks = await inspectProject(project);
+  if (options.json) {
+    stdout(JSON.stringify({ project, checks }, null, 2));
+  } else {
+    stdout(`Diagnóstico do Brandfy em ${project}`);
+    for (const check of checks) {
+      stdout(`${check.ok ? "✓" : "✗"} ${check.name}: ${check.detail}`);
+    }
+  }
+  return checks.every((check) => check.ok) ? 0 : 1;
 }
 
 /**

package/src/project.mjs

@@ -14,6 +14,28 @@ export const SKILL_DIRECTORIES = [
   ".claude/skills",
 ];
 
+export const REQUIRED_SKILLS = [
+  "brandfy",
+  "brandfy-setup",
+  "brandfy-mvp",
+  "brandfy-entrevista",
+  "brandfy-diagnostico",
+  "brandfy-estrategia",
+  "brandfy-naming",
+  "brandfy-slogan",
+  "brandfy-voz",
+  "brandfy-identidade-visual",
+  "brandfy-tipografia-web",
+  "brandfy-logo",
+  "brandfy-ativos-logo",
+  "brandfy-design-tokens",
+  "brandfy-aplicacoes",
+  "brandfy-templates-canais",
+  "brandfy-manual",
+  "brandfy-guia-pdf",
+  "brandfy-auditoria",
+];
+
 export async function exists(target) {
   try {
     await access(target);
@@ -51,15 +73,19 @@ function supportsRequiredNode(version) {
  * @returns {Promise<Array<{name: string, ok: boolean, detail: string}>>}
  */
 export async function inspectProject(project) {
-  const setup = await locateSkillScript(
-    project,
-    "brandfy-setup",
-    "scripts/setup.mjs",
-  );
   const agentsPath = path.join(project, "AGENTS.md");
   const agents = await exists(agentsPath)
     ? await readFile(agentsPath, "utf8")
     : "";
+  const installedSkills = await Promise.all(
+    REQUIRED_SKILLS.map(async (skill) => ({
+      skill,
+      path: await locateSkillScript(project, skill, "SKILL.md"),
+    })),
+  );
+  const missingSkills = installedSkills
+    .filter(({ path: skillPath }) => !skillPath)
+    .map(({ skill }) => skill);
 
   return [
     {
@@ -68,11 +94,11 @@ export async function inspectProject(project) {
       detail: `versão ${process.versions.node}`,
     },
     {
-      name: "Skills do Brandfy",
-      ok: Boolean(setup),
-      detail: setup
-        ? path.relative(project, setup)
-        : "brandfy-setup não foi encontrada",
+      name: "Biblioteca do Brandfy",
+      ok: missingSkills.length === 0,
+      detail: missingSkills.length === 0
+        ? `${REQUIRED_SKILLS.length} skills instaladas`
+        : `ausentes: ${missingSkills.join(", ")}`,
     },
     {
       name: "Lock das skills",
@@ -85,7 +111,12 @@ export async function inspectProject(project) {
       detail: ".brandfy/config.yaml",
     },
     {
-      name: "Manual editável",
+      name: "Guia da marca",
+      ok: await exists(path.join(project, "BRAND.md")),
+      detail: "BRAND.md",
+    },
+    {
+      name: "Índice da marca",
       ok: await exists(path.join(project, "brand", "README.md")),
       detail: "brand/README.md",
     },
@@ -95,5 +126,12 @@ export async function inspectProject(project) {
         && agents.includes("<!-- brandfy:consumer:end -->"),
       detail: "bloco gerenciado no AGENTS.md",
     },
+    {
+      name: "MVP.md",
+      ok: true,
+      detail: await exists(path.join(project, "MVP.md"))
+        ? "detectado; será lido pela skill brandfy-mvp"
+        : "não presente; entrada opcional",
+    },
   ];
 }