@promovaweb/brandfy 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog do pacote npm
+
+O changelog canônico da release fica em
+[`../CHANGELOG.md`](../CHANGELOG.md), pois o CLI, o framework e a documentação
+usam a mesma SemVer.
+
+## [1.1.0] - 2026-07-30
+
+- Primeira publicação do comando `brandfy`.
+- Instalação e atualização das skills por meio do pacote `skills`.
+- Comandos de setup, diagnóstico, PDF e auditoria.
+
+[1.1.0]: https://github.com/promovaweb/brandfy/releases/tag/v1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Promovaweb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# 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`.
+
+## Instalação
+
+Instale o executável globalmente:
+
+```bash
+npm install --global @promovaweb/brandfy
+brandfy init .
+```
+
+Também é possível executar sem instalação global:
+
+```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
+
+| 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:
+
+```bash
+brandfy pdf . -- --output brand/manual-da-marca.pdf
+```
+
+## Atualizações
+
+O framework e o CLI compartilham a mesma SemVer. Atualize o executável pelo npm
+e, dentro do projeto, atualize as skills:
+
+```bash
+npm install --global @promovaweb/brandfy@latest
+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.
+
+## Desenvolvimento
+
+Na raiz do repositório Brandfy, instale as dependências e execute os testes:
+
+```bash
+npm --prefix cli ci
+npm run cli:test
+npm run release:check
+```
+
+Consulte [`RELEASING.md`](../RELEASING.md) para atualizar a versão, gerar a
+documentação, publicar no npm e criar a tag e a GitHub Release.

package/bin/brandfy.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+/**
+ * Expõe o executável público do Brandfy.
+ *
+ * O arquivo permanece pequeno para que toda a lógica possa ser importada e
+ * exercitada pela suíte sem iniciar outro processo.
+ */
+
+import { main } from "../src/cli.mjs";
+
+await main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@promovaweb/brandfy",
+  "version": "1.1.0",
+  "description": "CLI do Brandfy para instalar skills e manter sistemas de marca em projetos com agentes.",
+  "type": "module",
+  "bin": {
+    "brandfy": "bin/brandfy.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "prepack": "npm test"
+  },
+  "engines": {
+    "node": ">=22.20.0"
+  },
+  "keywords": [
+    "agents",
+    "branding",
+    "brand",
+    "cli",
+    "skills"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/promovaweb/brandfy.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/promovaweb/brandfy/issues"
+  },
+  "homepage": "https://github.com/promovaweb/brandfy#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "skills": "1.5.21"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,254 @@
+/**
+ * Implementa a interface de linha de comando 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.
+ */
+
+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";
+
+const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+const packageManifest = JSON.parse(
+  await readFile(path.join(packageRoot, "package.json"), "utf8"),
+);
+
+export const DEFAULT_SOURCE = "promovaweb/brandfy";
+export const DEFAULT_AGENT = "codex";
+
+const HELP = `Brandfy ${packageManifest.version}
+
+Instala as skills do Brandfy e executa os geradores 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
+
+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
+
+Os argumentos escritos depois de -- seguem para o gerador de PDF ou auditoria.
+`;
+
+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") {
+      options.json = true;
+    } else if (argument.startsWith("-")) {
+      throw new Error(`Opção desconhecida: ${argument}`);
+    } else {
+      positional.push(argument);
+    }
+  }
+
+  return { positional, passthrough, options };
+}
+
+function projectFrom(value, cwd) {
+  return path.resolve(cwd, value || ".");
+}
+
+async function ensureSuccess(result, action) {
+  if (result.code !== 0) {
+    const detail = result.stderr?.trim() || result.stdout?.trim();
+    throw new Error(detail ? `${action}: ${detail}` : `${action}.`);
+  }
+}
+
+async function installSkills(runner, project, options, label) {
+  console.log(`${label} as skills do Brandfy em ${project}...`);
+  const result = await runner.runSkills([
+    "add",
+    options.source,
+    "--agent",
+    options.agent,
+    "--skill",
+    "*",
+    "-y",
+    "--copy",
+  ], project);
+  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);
+  if (!script) {
+    throw new Error(
+      `A skill ${skill} não está instalada. Execute brandfy init primeiro.`,
+    );
+  }
+  const result = await runner.runScript(script, args, project);
+  await ensureSuccess(result, `O script da skill ${skill} falhou`);
+}
+
+/**
+ * Executa um comando com dependências injetáveis para permitir testes isolados.
+ *
+ * @param {string[]} argv Argumentos sem `node` e sem o nome do binário.
+ * @param {{cwd?: string, runner?: object, stdout?: Function}} dependencies
+ * Dependências substituíveis pela suíte.
+ * @returns {Promise<number>} Código de saída.
+ */
+export async function execute(argv, dependencies = {}) {
+  const cwd = dependencies.cwd || process.cwd();
+  const runner = dependencies.runner || createProcessRunner();
+  const stdout = dependencies.stdout || console.log;
+
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+    stdout(HELP.trimEnd());
+    return 0;
+  }
+  if (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version") {
+    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;
+  }
+
+  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 (command === "pdf") {
+    await runInstalledScript(
+      runner,
+      project,
+      "brandfy-guia-pdf",
+      "scripts/build-brand-guide.mjs",
+      ["--project", project, ...passthrough],
+    );
+    return 0;
+  }
+
+  if (command === "audit") {
+    await runInstalledScript(
+      runner,
+      project,
+      "brandfy-auditoria",
+      "scripts/audit-brand.mjs",
+      ["--project", project, ...passthrough],
+    );
+    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}.`);
+    return 0;
+  }
+
+  throw new Error(`Comando desconhecido: ${command || "(vazio)"}`);
+}
+
+/**
+ * Converte falhas esperadas em uma mensagem curta de terminal.
+ *
+ * @param {string[]} argv Argumentos do processo.
+ * @returns {Promise<void>}
+ */
+export async function main(argv) {
+  try {
+    process.exitCode = await execute(argv);
+  } catch (error) {
+    console.error(`Erro: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/src/process-runner.mjs

@@ -0,0 +1,86 @@
+/**
+ * Executa o gerenciador `skills` e os scripts instalados pelo Brandfy.
+ *
+ * A resolução parte da dependência empacotada, portanto o CLI não depende de
+ * um comando `skills` global nem baixa uma versão diferente a cada execução.
+ */
+
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Executa um processo filho com o terminal herdado.
+ *
+ * @param {string} command Executável que será iniciado.
+ * @param {string[]} args Argumentos entregues ao executável.
+ * @param {string} cwd Diretório usado durante a execução.
+ * @param {"inherit" | "pipe"} stdio Forma de encaminhar a saída.
+ * @returns {Promise<{code: number, stdout: string, stderr: string}>}
+ */
+export function runProcess(command, args, cwd, stdio = "inherit") {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: stdio === "inherit" ? "inherit" : ["ignore", "pipe", "pipe"],
+      env: process.env,
+    });
+    let stdout = "";
+    let stderr = "";
+
+    if (stdio === "pipe") {
+      child.stdout.setEncoding("utf8");
+      child.stderr.setEncoding("utf8");
+      child.stdout.on("data", (chunk) => {
+        stdout += chunk;
+      });
+      child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+      });
+    }
+
+    child.once("error", reject);
+    child.once("close", (code) => {
+      resolve({ code: code ?? 1, stdout, stderr });
+    });
+  });
+}
+
+/**
+ * Localiza o binário distribuído pela dependência npm `skills`.
+ *
+ * @returns {Promise<string>} Caminho absoluto do arquivo executável.
+ */
+export async function resolveSkillsCli() {
+  const packagePath = require.resolve("skills/package.json");
+  const manifest = JSON.parse(await readFile(packagePath, "utf8"));
+  const relativeBin = typeof manifest.bin === "string"
+    ? manifest.bin
+    : manifest.bin?.skills;
+
+  if (!relativeBin) {
+    throw new Error("A dependência skills não expõe o executável esperado.");
+  }
+
+  return path.resolve(path.dirname(packagePath), relativeBin);
+}
+
+/**
+ * Cria o adaptador usado pelos comandos do Brandfy.
+ *
+ * @returns {{runSkills: Function, runScript: Function}} Adaptador de processos.
+ */
+export function createProcessRunner() {
+  return {
+    async runSkills(args, cwd, stdio = "inherit") {
+      const executable = await resolveSkillsCli();
+      return runProcess(process.execPath, [executable, ...args], cwd, stdio);
+    },
+    runScript(script, args, cwd, stdio = "inherit") {
+      return runProcess(process.execPath, [script, ...args], cwd, stdio);
+    },
+  };
+}

package/src/project.mjs

@@ -0,0 +1,99 @@
+/**
+ * Resolve a instalação do Brandfy e confere o estado do projeto consumidor.
+ *
+ * A busca aceita os diretórios usados pelos agentes mais comuns, mas o CLI
+ * instala no escopo do projeto para manter o lock junto do repositório.
+ */
+
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+
+export const SKILL_DIRECTORIES = [
+  ".agents/skills",
+  ".codex/skills",
+  ".claude/skills",
+];
+
+export async function exists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Localiza um script pertencente a uma skill instalada.
+ *
+ * @param {string} project Diretório absoluto do projeto consumidor.
+ * @param {string} skill Nome da skill.
+ * @param {string} script Caminho relativo dentro da skill.
+ * @returns {Promise<string | null>} Caminho encontrado ou `null`.
+ */
+export async function locateSkillScript(project, skill, script) {
+  for (const directory of SKILL_DIRECTORIES) {
+    const candidate = path.join(project, directory, skill, script);
+    if (await exists(candidate)) return candidate;
+  }
+  return null;
+}
+
+function supportsRequiredNode(version) {
+  const [major, minor] = version.split(".").map(Number);
+  return major > 22 || (major === 22 && minor >= 20);
+}
+
+/**
+ * Produz as verificações exibidas por `brandfy doctor`.
+ *
+ * @param {string} project Diretório absoluto do projeto.
+ * @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")
+    : "";
+
+  return [
+    {
+      name: "Node.js",
+      ok: supportsRequiredNode(process.versions.node),
+      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: "Lock das skills",
+      ok: await exists(path.join(project, "skills-lock.json")),
+      detail: "skills-lock.json",
+    },
+    {
+      name: "Configuração",
+      ok: await exists(path.join(project, ".brandfy", "config.yaml")),
+      detail: ".brandfy/config.yaml",
+    },
+    {
+      name: "Manual editável",
+      ok: await exists(path.join(project, "brand", "README.md")),
+      detail: "brand/README.md",
+    },
+    {
+      name: "Instruções do agente",
+      ok: agents.includes("<!-- brandfy:consumer:start -->")
+        && agents.includes("<!-- brandfy:consumer:end -->"),
+      detail: "bloco gerenciado no AGENTS.md",
+    },
+  ];
+}