melvex-design 1.0.0

package/README.md

@@ -0,0 +1,142 @@
+# Melvex Design
+
+Skill de direção de arte autônoma, UX, conteúdo e implementação frontend para transformar até um briefing sem instruções estéticas em um site autoral, acessível, rápido, responsivo e sem aparência genérica de IA.
+
+Ela preserva a stack existente e funciona diretamente com React, Next.js, Vite, Astro e HTML/CSS. Em WordPress, Webflow e Framer, a implementação depende das ferramentas e do acesso disponíveis.
+
+## Requisitos
+
+- Node.js 22.20 ou superior com `npx`.
+- Um agente compatível com o formato de skills.
+- Acesso de escrita à pasta de configuração do usuário.
+
+## Instalação recomendada
+
+Instale no Codex com o comando próprio da Melvex:
+
+```powershell
+npx melvex-design
+```
+
+Esse é o instalador oficial da Melvex. Ele mostra somente a interface da marca, executa o mecanismo do Skills CLI em segundo plano e verifica `SKILL.md` e os recursos essenciais antes de informar sucesso. O Codex é o destino padrão para evitar instalações desnecessárias em dezenas de agentes.
+
+Para escolher outro agente:
+
+```powershell
+npx melvex-design --agent cursor
+```
+
+Para instalar em mais de um:
+
+```powershell
+npx melvex-design --agent codex --agent claude-code --agent cursor
+```
+
+Use todos os agentes somente quando isso for realmente desejado:
+
+```powershell
+npx melvex-design --all-agents
+```
+
+Para diagnóstico, mostre também a saída técnica capturada do Skills CLI:
+
+```powershell
+npx melvex-design --verbose
+```
+
+Confira todas as opções sem instalar:
+
+```powershell
+npx melvex-design --help
+npx melvex-design --dry-run
+```
+
+## Instalação direta pelo Skills CLI
+
+O comando externo continua disponível como alternativa:
+
+```powershell
+npx skills add jaop2158-sketch/melvex-design --skill melvex-design --global --yes --agent codex
+```
+
+O visual dessa alternativa pertence ao pacote `skills`, não à Melvex. Ela instala a skill, mas não instala o programa Codex CLI. O comando `npx skills use ... --agent codex` só consegue abrir o agente quando `codex --version` já funciona no terminal.
+
+## Instalador alternativo para PowerShell
+
+Para uma instalação guiada sem depender do pacote `melvex-design` publicado no npm, use o script PowerShell. Ele apresenta as etapas da Melvex, verifica os arquivos essenciais e captura a saída original do Skills CLI para não misturar as duas interfaces.
+
+Baixe e inspecione antes de executar:
+
+```powershell
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/jaop2158-sketch/melvex-design/main/install.ps1" -OutFile ".\install-melvex.ps1"
+Get-Content ".\install-melvex.ps1"
+powershell -ExecutionPolicy Bypass -File ".\install-melvex.ps1"
+```
+
+Para diagnóstico, exiba também a saída original capturada:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File ".\install-melvex.ps1" -ShowCliOutput
+```
+
+Por segurança, o instalador não cria arquivos no projeto atual por padrão. Para também registrar o workflow `/melvex-design`, execute dentro do projeto ou informe o caminho:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File ".\install-melvex.ps1" -InstallWorkflow -ProjectPath "C:\caminho\do\projeto"
+```
+
+Para substituir um workflow Melvex diferente, criando backup:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File ".\install-melvex.ps1" -InstallWorkflow -ForceWorkflow -ProjectPath "C:\caminho\do\projeto"
+```
+
+## Verificar a instalação
+
+PowerShell:
+
+```powershell
+Test-Path "$env:USERPROFILE\.agents\skills\melvex-design\SKILL.md"
+Select-String -Path "$env:USERPROFILE\.agents\skills\melvex-design\SKILL.md" -Pattern "^name: melvex-design$"
+```
+
+Bash:
+
+```bash
+test -f ~/.agents/skills/melvex-design/SKILL.md
+grep -q '^name: melvex-design$' ~/.agents/skills/melvex-design/SKILL.md
+```
+
+Se a instalação estiver correta mas a skill ainda não aparecer, atualize a lista de skills ou abra uma nova sessão do agente.
+
+## Uso
+
+- Antigravity e Claude Code: `/melvex-design <briefing>`
+- Codex: `$melvex-design <briefing>`
+- Cursor e demais agentes: mencione `melvex-design` ou use o mecanismo de skills da plataforma.
+
+Exemplo:
+
+```text
+$melvex-design Crie um site premium para uma clínica, preserve a stack atual, não invente avaliações e valide mobile, acessibilidade e performance.
+```
+
+Você não precisa descrever o design. Um briefing focado apenas em conteúdo também deve gerar direção visual completa:
+
+```text
+$melvex-design Crie um site para uma oficina de restauração de móveis. Preciso de início, serviços, processo, trabalhos realizados e contato. O objetivo é receber pedidos de orçamento pelo WhatsApp.
+```
+
+A skill deve inferir conceito, tipografia, paleta, composição, mídia, gesto visual, movimento e adaptação mobile a partir do assunto. Site básico significa menos complexidade funcional, não visual sem personalidade.
+
+Também é possível pedir uma auditoria sem edição:
+
+```text
+$melvex-design Audite este site e priorize os problemas, mas não altere nenhum arquivo.
+```
+
+## Limitações
+
+- Pesquisa de referências depende de acesso web.
+- Métricas reais de Core Web Vitals exigem dados ou ferramentas adequadas; a skill não inventa notas.
+- Publicação, serviços externos e alterações em produção continuam exigindo autorização explícita.

package/bin/melvex-design.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from "../src/cli.js";
+
+process.exitCode = await run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "melvex-design",
+  "version": "1.0.0",
+  "description": "Instalador oficial da skill Melvex Design com uma experiência de terminal própria.",
+  "type": "module",
+  "bin": {
+    "melvex-design": "bin/melvex-design.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "lint": "node --check bin/melvex-design.js && node --check src/cli.js",
+    "test": "node --test",
+    "package:check": "npm pack --dry-run",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "keywords": [
+    "agent-skills",
+    "ai-design",
+    "codex",
+    "frontend-design",
+    "web-design"
+  ],
+  "author": "jaop2158-sketch",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jaop2158-sketch/melvex-design.git"
+  },
+  "homepage": "https://github.com/jaop2158-sketch/melvex-design#readme",
+  "bugs": {
+    "url": "https://github.com/jaop2158-sketch/melvex-design/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.20.0"
+  },
+  "dependencies": {
+    "skills": "1.5.21"
+  }
+}

package/src/cli.js

@@ -0,0 +1,417 @@
+import { spawn } from "node:child_process";
+import { constants as fsConstants } from "node:fs";
+import { access, readFile, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+
+const require = createRequire(import.meta.url);
+
+export const PACKAGE_NAME = "melvex-design";
+export const PACKAGE_VERSION = "1.0.0";
+export const SKILL_NAME = "melvex-design";
+export const SKILL_SOURCE = "jaop2158-sketch/melvex-design";
+export const DEFAULT_AGENTS = ["codex"];
+
+const REQUIRED_FILES = [
+  "SKILL.md",
+  "references/visual-direction.md",
+  "references/quality-gates.md",
+  "scripts/ui-static-audit.mjs",
+];
+
+const ANSI = {
+  reset: "\u001b[0m",
+  bold: "\u001b[1m",
+  dim: "\u001b[2m",
+  magenta: "\u001b[35m",
+  brightMagenta: "\u001b[95m",
+  cyan: "\u001b[36m",
+  green: "\u001b[32m",
+  yellow: "\u001b[33m",
+  red: "\u001b[31m",
+  white: "\u001b[97m",
+};
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+function splitAgents(value) {
+  return value
+    .split(",")
+    .map((agent) => agent.trim())
+    .filter(Boolean);
+}
+
+export function parseArgs(argv) {
+  const options = {
+    agents: [],
+    allAgents: false,
+    verbose: false,
+    dryRun: false,
+    color: Boolean(process.stdout.isTTY) && !process.env.NO_COLOR,
+    help: false,
+    version: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+
+    if (argument === "--agent" || argument === "-a") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Informe um agente depois de --agent.");
+      }
+      options.agents.push(...splitAgents(value));
+      index += 1;
+      continue;
+    }
+
+    if (argument.startsWith("--agent=")) {
+      options.agents.push(...splitAgents(argument.slice("--agent=".length)));
+      continue;
+    }
+
+    if (argument === "--all-agents") {
+      options.allAgents = true;
+      continue;
+    }
+
+    if (argument === "--verbose") {
+      options.verbose = true;
+      continue;
+    }
+
+    if (argument === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (argument === "--no-color") {
+      options.color = false;
+      continue;
+    }
+
+    if (argument === "--help" || argument === "-h") {
+      options.help = true;
+      continue;
+    }
+
+    if (argument === "--version" || argument === "-V") {
+      options.version = true;
+      continue;
+    }
+
+    throw new Error(`Opção desconhecida: ${argument}`);
+  }
+
+  options.agents = unique(options.agents);
+  if (options.allAgents && options.agents.length > 0) {
+    throw new Error("Use --all-agents ou --agent, não os dois juntos.");
+  }
+  if (!options.allAgents && options.agents.length === 0) {
+    options.agents = [...DEFAULT_AGENTS];
+  }
+
+  return options;
+}
+
+export function buildSkillsArgs(options) {
+  const args = [
+    "add",
+    SKILL_SOURCE,
+    "--skill",
+    SKILL_NAME,
+    "--global",
+    "--yes",
+  ];
+
+  if (options.allAgents) {
+    args.push("--agent", "*");
+    return args;
+  }
+
+  for (const agent of options.agents) {
+    args.push("--agent", agent);
+  }
+  return args;
+}
+
+function paint(enabled, color, value) {
+  return enabled ? `${ANSI[color]}${value}${ANSI.reset}` : value;
+}
+
+function printBanner(color) {
+  const edge = paint(color, "brightMagenta", "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+  console.log("");
+  console.log(`  ${edge}`);
+  console.log(
+    `  ${paint(color, "bold", "MELVEX")} ${paint(color, "brightMagenta", "/ DESIGN")}`,
+  );
+  console.log(`  ${paint(color, "dim", "Direção visual autônoma para agentes de IA")}`);
+  console.log(`  ${edge}`);
+  console.log("");
+}
+
+function printStep(number, total, label, color) {
+  const marker = paint(color, "brightMagenta", `◆ ${number}/${total}`);
+  console.log(`${marker}  ${paint(color, "white", label)}`);
+}
+
+function printSuccess(message, color) {
+  console.log(`${paint(color, "green", "✓")}  ${message}`);
+}
+
+function printInfo(message, color) {
+  console.log(`${paint(color, "cyan", "i")}  ${message}`);
+}
+
+function printWarning(message, color) {
+  console.log(`${paint(color, "yellow", "!")}  ${message}`);
+}
+
+function printError(message, color) {
+  console.error(`${paint(color, "red", "×")}  ${message}`);
+}
+
+export function helpText() {
+  return `Melvex Design ${PACKAGE_VERSION}
+
+Instala a skill Melvex Design com uma interface própria.
+
+Uso:
+  npx melvex-design [opções]
+
+Opções:
+  -a, --agent <nome>   Instalar em um agente. Pode ser repetido.
+      --all-agents     Instalar em todos os agentes suportados.
+      --verbose        Mostrar a saída técnica do Skills CLI.
+      --dry-run        Mostrar o que seria executado sem instalar.
+      --no-color       Desativar cores ANSI.
+  -h, --help           Mostrar esta ajuda.
+  -V, --version        Mostrar a versão.
+
+Exemplos:
+  npx melvex-design
+  npx melvex-design --agent cursor
+  npx melvex-design -a codex -a claude-code
+  npx melvex-design --all-agents
+
+Sem opções, a instalação é direcionada ao Codex.`;
+}
+
+function resolveSkillsBinary() {
+  try {
+    return require.resolve("skills/bin/cli.mjs");
+  } catch (error) {
+    if (error.code === "MODULE_NOT_FOUND") {
+      throw new Error(
+        "A dependência interna 'skills' não está instalada. Se estiver testando o código clonado, execute npm ci e tente novamente.",
+      );
+    }
+    throw error;
+  }
+}
+
+function startSpinner(label, color, verbose) {
+  if (!process.stdout.isTTY || verbose) {
+    printInfo(label, color);
+    return () => {};
+  }
+
+  const frames = ["◒", "◐", "◓", "◑"];
+  let frame = 0;
+  const render = () => {
+    const symbol = paint(color, "brightMagenta", frames[frame % frames.length]);
+    process.stdout.write(`\r${symbol}  ${label}`);
+    frame += 1;
+  };
+  render();
+  const timer = setInterval(render, 90);
+
+  return () => {
+    clearInterval(timer);
+    process.stdout.write("\r\u001b[2K");
+  };
+}
+
+async function executeSkills(args, options) {
+  const skillsBinary = resolveSkillsBinary();
+  const output = [];
+  const child = spawn(process.execPath, [skillsBinary, ...args], {
+    env: {
+      ...process.env,
+      FORCE_COLOR: "0",
+      NO_COLOR: "1",
+    },
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+
+  const collect = (chunk) => {
+    const text = chunk.toString();
+    output.push(text);
+    if (options.verbose) {
+      process.stdout.write(paint(options.color, "dim", text));
+    }
+  };
+
+  child.stdout.on("data", collect);
+  child.stderr.on("data", collect);
+
+  return new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code, signal) => {
+      resolve({
+        code: code ?? 1,
+        signal,
+        output: output.join(""),
+      });
+    });
+  });
+}
+
+function candidateSkillDirectories(homeDirectories) {
+  const relativeDirectories = [
+    [".agents", "skills", SKILL_NAME],
+    [".config", "agents", "skills", SKILL_NAME],
+    [".codex", "skills", SKILL_NAME],
+    [".claude", "skills", SKILL_NAME],
+    [".cursor", "skills", SKILL_NAME],
+  ];
+
+  return unique(homeDirectories.filter(Boolean)).flatMap((home) =>
+    relativeDirectories.map((parts) => path.join(home, ...parts)),
+  );
+}
+
+export async function verifyInstalledSkill(homeDirectories = [os.homedir()]) {
+  const checked = [];
+
+  for (const directory of candidateSkillDirectories(homeDirectories)) {
+    checked.push(directory);
+    const skillFile = path.join(directory, "SKILL.md");
+    try {
+      await access(skillFile, fsConstants.R_OK);
+      const content = await readFile(skillFile, "utf8");
+      if (!/^name:\s*melvex-design\s*$/m.test(content)) {
+        continue;
+      }
+      for (const requiredFile of REQUIRED_FILES) {
+        await access(path.join(directory, ...requiredFile.split("/")), fsConstants.R_OK);
+      }
+      return { directory, checked };
+    } catch {
+      // Continue looking through canonical and agent-specific install paths.
+    }
+  }
+
+  return { directory: null, checked };
+}
+
+async function saveDiagnosticLog(content) {
+  const filename = `melvex-design-${Date.now()}.log`;
+  const logPath = path.join(os.tmpdir(), filename);
+  await writeFile(logPath, content || "Nenhuma saída foi recebida do Skills CLI.\n", {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  return logPath;
+}
+
+function resolveHomeDirectories() {
+  return unique([
+    os.homedir(),
+    process.env.USERPROFILE,
+    process.env.HOME,
+  ].filter(Boolean));
+}
+
+export async function run(argv) {
+  let options;
+  try {
+    options = parseArgs(argv);
+  } catch (error) {
+    printError(error.message, Boolean(process.stderr.isTTY) && !process.env.NO_COLOR);
+    console.error("Use npx melvex-design --help para ver as opções.");
+    return 2;
+  }
+
+  if (options.version) {
+    console.log(PACKAGE_VERSION);
+    return 0;
+  }
+  if (options.help) {
+    console.log(helpText());
+    return 0;
+  }
+
+  printBanner(options.color);
+  const totalSteps = 4;
+
+  printStep(1, totalSteps, "Verificando o ambiente", options.color);
+  printSuccess(`Node.js ${process.versions.node}`, options.color);
+  printSuccess("Instalador oficial da Melvex carregado", options.color);
+
+  printStep(2, totalSteps, "Preparando a instalação", options.color);
+  const target = options.allAgents ? "todos os agentes suportados" : options.agents.join(", ");
+  printInfo(`Destino: ${target}`, options.color);
+  printInfo(`Fonte: github.com/${SKILL_SOURCE}`, options.color);
+
+  const skillsArgs = buildSkillsArgs(options);
+  if (options.dryRun) {
+    printWarning("Simulação: nenhum arquivo foi alterado.", options.color);
+    console.log(`skills ${skillsArgs.join(" ")}`);
+    return 0;
+  }
+
+  printStep(3, totalSteps, "Instalando a skill", options.color);
+  const stopSpinner = startSpinner(
+    "Baixando e configurando Melvex Design...",
+    options.color,
+    options.verbose,
+  );
+  let result;
+  try {
+    result = await executeSkills(skillsArgs, options);
+  } catch (error) {
+    stopSpinner();
+    printError(`Não foi possível iniciar a instalação: ${error.message}`, options.color);
+    return 1;
+  }
+  stopSpinner();
+
+  printStep(4, totalSteps, "Validando os arquivos instalados", options.color);
+  const verification = await verifyInstalledSkill(resolveHomeDirectories());
+
+  if (!verification.directory) {
+    const logPath = await saveDiagnosticLog(result.output);
+    printError("A skill não foi encontrada nos locais esperados.", options.color);
+    printInfo(`Diagnóstico salvo em: ${logPath}`, options.color);
+    printInfo("Execute novamente com --verbose para acompanhar os detalhes.", options.color);
+    return 1;
+  }
+
+  printSuccess("SKILL.md e recursos essenciais verificados", options.color);
+  if (result.code !== 0) {
+    const logPath = await saveDiagnosticLog(result.output);
+    printWarning("A skill principal foi instalada, mas uma integração opcional falhou.", options.color);
+    printInfo(`Diagnóstico salvo em: ${logPath}`, options.color);
+  }
+
+  console.log("");
+  console.log(paint(options.color, "green", "  INSTALAÇÃO CONCLUÍDA"));
+  console.log("");
+  console.log(`  Skill     ${paint(options.color, "white", SKILL_NAME)}`);
+  console.log(`  Local     ${paint(options.color, "dim", verification.directory)}`);
+  console.log(`  Agentes   ${paint(options.color, "dim", target)}`);
+  console.log("");
+  console.log(paint(options.color, "brightMagenta", "  Teste agora com:"));
+  console.log(
+    "  $melvex-design Crie um site bonito para uma clínica. Infira toda a direção visual.",
+  );
+  console.log("");
+  printInfo("Se a skill ainda não aparecer, atualize a lista de skills do agente.", options.color);
+  return 0;
+}