@lugom.io/hefesto 0.1.2 → 0.3.0

package/skills/hefesto-design/scripts/search.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""CLI de busca multi-domínio para o sistema de design do Hefesto.
+
+Busca em CSVs de estilos, cores, tipografia, componentes, UX, anti-patterns,
+espaçamento e animações usando BM25.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Resolve import do core.py no mesmo diretório
+_SCRIPT_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(_SCRIPT_DIR))
+
+from core import BM25
+
+DATA_DIR = _SCRIPT_DIR.parent / "data"
+
+DOMAINS = {
+    "style": {
+        "csv": "styles.csv",
+        "fields": ["name", "keywords_pt", "keywords_en", "description", "mood", "best_for"],
+        "label": "Estilos",
+    },
+    "color": {
+        "csv": "colors.csv",
+        "fields": ["name", "industry", "mood", "description"],
+        "label": "Paletas de Cores",
+    },
+    "typography": {
+        "csv": "typography.csv",
+        "fields": ["name", "mood", "best_for", "display_font", "body_font", "pairing_reason"],
+        "label": "Tipografia",
+    },
+    "component": {
+        "csv": "components.csv",
+        "fields": ["name", "category", "variants", "description"],
+        "label": "Componentes",
+    },
+    "ux": {
+        "csv": "ux-rules.csv",
+        "fields": ["name", "category", "rule", "standard", "reasoning"],
+        "label": "Regras de UX",
+    },
+    "anti-pattern": {
+        "csv": "anti-patterns.csv",
+        "fields": ["name", "category", "description", "why_bad"],
+        "label": "Anti-Patterns",
+    },
+    "spacing": {
+        "csv": "spacing.csv",
+        "fields": ["name", "style", "description", "density"],
+        "label": "Espaçamento",
+    },
+    "animation": {
+        "csv": "animations.csv",
+        "fields": ["name", "context", "description"],
+        "label": "Animações",
+    },
+    "product": {
+        "csv": "products.csv",
+        "fields": ["name", "category", "audience", "recommended_style", "key_components", "layout_pattern", "description"],
+        "label": "Tipos de Produto",
+    },
+    "chart": {
+        "csv": "charts.csv",
+        "fields": ["name", "category", "best_for", "data_type", "a11y_notes", "description"],
+        "label": "Gráficos e Visualização",
+    },
+    "landing": {
+        "csv": "landing-pages.csv",
+        "fields": ["name", "section_type", "purpose", "key_elements", "copywriting_pattern", "description"],
+        "label": "Landing Pages",
+    },
+    "icon": {
+        "csv": "icons.csv",
+        "fields": ["name", "style", "best_for", "avoid_with", "description"],
+        "label": "Icon Sets",
+    },
+    "font": {
+        "csv": "google-fonts.csv",
+        "fields": ["name", "category", "mood", "best_for", "pair_with", "description"],
+        "label": "Google Fonts",
+    },
+}
+
+
+def _get_engine(domain_key):
+    """Cria um BM25 engine para o domínio dado."""
+    domain = DOMAINS[domain_key]
+    csv_path = DATA_DIR / domain["csv"]
+    if not csv_path.exists():
+        print(f"Erro: arquivo não encontrado: {csv_path}", file=sys.stderr)
+        sys.exit(1)
+    return BM25(str(csv_path), domain["fields"])
+
+
+def _display_columns(results):
+    """Determina colunas visíveis (exclui internas e muito longas)."""
+    if not results:
+        return []
+    skip = {"_score"}
+    return [k for k in results[0].keys() if k not in skip]
+
+
+def _format_table(results, domain_label, max_col_width=40):
+    """Formata resultados como tabela alinhada."""
+    if not results:
+        return f"  Nenhum resultado encontrado para '{domain_label}'."
+
+    cols = _display_columns(results)
+    cols_with_score = cols + ["score"]
+
+    # Calcula largura de cada coluna
+    widths = {}
+    for col in cols_with_score:
+        header_len = len(col)
+        max_val = 0
+        for r in results:
+            val = str(r.get("_score", "")) if col == "score" else str(r.get(col, ""))
+            if len(val) > max_col_width:
+                val = val[:max_col_width - 3] + "..."
+            max_val = max(max_val, len(val))
+        widths[col] = max(header_len, min(max_val, max_col_width))
+
+    # Header
+    header = " | ".join(col.ljust(widths[col]) for col in cols_with_score)
+    separator = "-+-".join("-" * widths[col] for col in cols_with_score)
+
+    lines = [f"\n  === {domain_label} ===\n", f"  {header}", f"  {separator}"]
+
+    for r in results:
+        row_parts = []
+        for col in cols_with_score:
+            val = str(r.get("_score", "")) if col == "score" else str(r.get(col, ""))
+            if len(val) > max_col_width:
+                val = val[:max_col_width - 3] + "..."
+            row_parts.append(val.ljust(widths[col]))
+        lines.append("  " + " | ".join(row_parts))
+
+    return "\n".join(lines)
+
+
+def _search_domain(domain_key, query, max_results):
+    """Busca em um domínio e retorna resultados."""
+    engine = _get_engine(domain_key)
+    return engine.search(query, max_results)
+
+
+def _list_domains():
+    """Lista todos os domínios disponíveis."""
+    print("\nDomínios disponíveis:\n")
+    for key, info in DOMAINS.items():
+        csv_path = DATA_DIR / info["csv"]
+        exists = "OK" if csv_path.exists() else "FALTANDO"
+        print(f"  {key:15s}  {info['label']:25s}  [{exists}] {info['csv']}")
+    print()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Busca multi-domínio no sistema de design Hefesto.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""Exemplos:
+  python3 search.py "fintech modern" --domain style
+  python3 search.py "luxury serif" --domain typography
+  python3 search.py "wellness calm" --all
+  python3 search.py --list-domains
+""",
+    )
+    parser.add_argument("query", nargs="?", default=None, help="Termos de busca")
+    parser.add_argument(
+        "--domain", "-d",
+        choices=list(DOMAINS.keys()),
+        help="Domínio para buscar",
+    )
+    parser.add_argument("--all", "-a", action="store_true", help="Buscar em todos os domínios")
+    parser.add_argument("--list-domains", action="store_true", help="Listar domínios disponíveis")
+    parser.add_argument(
+        "-f", "--format",
+        choices=["table", "json"],
+        default="table",
+        help="Formato de saída (padrão: table)",
+    )
+    parser.add_argument(
+        "-n", "--max-results",
+        type=int,
+        default=5,
+        help="Número máximo de resultados por domínio (padrão: 5)",
+    )
+
+    args = parser.parse_args()
+
+    if args.list_domains:
+        _list_domains()
+        return
+
+    if not args.query:
+        parser.error("Informe os termos de busca ou use --list-domains.")
+
+    if not args.domain and not args.all:
+        parser.error("Informe --domain DOMÍNIO ou --all para buscar em todos.")
+
+    domains_to_search = list(DOMAINS.keys()) if args.all else [args.domain]
+
+    all_results = {}
+    for domain_key in domains_to_search:
+        try:
+            results = _search_domain(domain_key, args.query, args.max_results)
+            if results:
+                all_results[domain_key] = results
+        except FileNotFoundError:
+            if not args.all:
+                print(f"Erro: CSV do domínio '{domain_key}' não encontrado.", file=sys.stderr)
+                sys.exit(1)
+
+    if args.format == "json":
+        output = {}
+        for domain_key, results in all_results.items():
+            output[domain_key] = results
+        print(json.dumps(output, indent=2, ensure_ascii=False))
+    else:
+        if not all_results:
+            print("\n  Nenhum resultado encontrado.\n")
+            return
+        for domain_key, results in all_results.items():
+            label = DOMAINS[domain_key]["label"]
+            print(_format_table(results, label))
+        print()
+
+
+if __name__ == "__main__":
+    main()

package/skills/hefesto-design/scripts/validate_tokens.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""Validador de uso de design tokens para o Hefesto.
+
+Verifica se tokens definidos no DESIGN.md são usados no código-fonte e
+identifica valores hardcoded que deveriam usar tokens.
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+
+
+SCANNABLE_EXTENSIONS = {
+    ".tsx", ".jsx", ".vue", ".svelte", ".css", ".scss",
+    ".html", ".astro", ".ts", ".js",
+}
+
+
+def _is_binary(filepath):
+    """Verifica se o arquivo parece ser binário."""
+    try:
+        with open(filepath, "rb") as f:
+            chunk = f.read(1024)
+        return b"\x00" in chunk
+    except (IOError, OSError):
+        return True
+
+
+def parse_tokens(design_path):
+    """Extrai tokens de design da seção 'Tokens de Design' do DESIGN.md.
+
+    Retorna dict: {token_name: token_value}
+    Ex: {"--color-primary": "#6366f1", "--space-md": "16px"}
+    """
+    try:
+        with open(design_path, "r", encoding="utf-8") as f:
+            content = f.read()
+    except FileNotFoundError:
+        print(f"Erro: arquivo não encontrado: {design_path}", file=sys.stderr)
+        sys.exit(1)
+
+    tokens = {}
+    in_section = False
+
+    for line in content.split("\n"):
+        # Detecta início da seção de tokens
+        if re.match(r"^#{1,4}\s+.*[Tt]okens\s+de\s+[Dd]esign", line):
+            in_section = True
+            continue
+        # Detecta fim da seção (próximo heading de mesmo nível ou superior)
+        if in_section and re.match(r"^#{1,3}\s+", line) and "token" not in line.lower():
+            break
+        if not in_section:
+            continue
+
+        # Extrai custom properties CSS: --nome: valor
+        token_match = re.search(r"(--[\w-]+)\s*:\s*([^;}\n]+)", line)
+        if token_match:
+            name = token_match.group(1).strip()
+            value = token_match.group(2).strip().rstrip(";")
+            tokens[name] = value
+            continue
+
+        # Também captura tokens em formato de tabela markdown: | --nome | valor |
+        table_match = re.search(r"\|\s*(--[\w-]+)\s*\|\s*([^|]+)\s*\|", line)
+        if table_match:
+            name = table_match.group(1).strip()
+            value = table_match.group(2).strip()
+            tokens[name] = value
+            continue
+
+        # Formato com backtick: `--nome` → `valor` ou `--nome`: `valor`
+        backtick_match = re.search(r"`(--[\w-]+)`\s*[:\u2192→=]\s*`?([^`\n]+)`?", line)
+        if backtick_match:
+            name = backtick_match.group(1).strip()
+            value = backtick_match.group(2).strip().rstrip("`")
+            tokens[name] = value
+
+    return tokens
+
+
+def walk_source(src_dir):
+    """Percorre diretório fonte e retorna arquivos escaneáveis."""
+    files = []
+    for root, _dirs, filenames in os.walk(src_dir):
+        parts = root.split(os.sep)
+        if any(p in {"node_modules", ".git", "dist", "build", ".next", "__pycache__"} for p in parts):
+            continue
+        for fname in filenames:
+            ext = os.path.splitext(fname)[1].lower()
+            if ext in SCANNABLE_EXTENSIONS:
+                files.append(os.path.join(root, fname))
+    return files
+
+
+def validate_tokens(design_path, src_dir):
+    """Valida uso de tokens no código-fonte.
+
+    Retorna dict com:
+        tokens_defined: total de tokens definidos
+        tokens_used: set de tokens encontrados no código
+        tokens_unused: set de tokens não encontrados
+        hardcoded_matches: lista de {file, line, token_name, hardcoded_value}
+        coverage: percentual de cobertura
+    """
+    tokens = parse_tokens(design_path)
+    if not tokens:
+        print("Aviso: nenhum token encontrado na seção 'Tokens de Design'.", file=sys.stderr)
+        return {
+            "tokens_defined": 0,
+            "tokens_used": set(),
+            "tokens_unused": set(),
+            "hardcoded_matches": [],
+            "coverage": 0.0,
+        }
+
+    files = walk_source(src_dir)
+    tokens_used = set()
+    hardcoded_matches = []
+
+    # Pré-computa mapeamento valor → nomes de token (para detectar hardcoded)
+    value_to_tokens = {}
+    for name, value in tokens.items():
+        val_normalized = value.strip().lower()
+        if val_normalized and len(val_normalized) >= 2:
+            value_to_tokens.setdefault(val_normalized, []).append(name)
+
+    for filepath in files:
+        if _is_binary(filepath):
+            continue
+        try:
+            with open(filepath, "r", encoding="utf-8", errors="replace") as f:
+                lines = f.readlines()
+        except (IOError, OSError):
+            continue
+
+        file_content = "".join(lines)
+
+        # Verifica quais tokens são usados
+        for token_name in tokens:
+            if token_name in file_content:
+                tokens_used.add(token_name)
+
+        # Busca valores hardcoded que correspondem a valores de tokens
+        for lineno, line in enumerate(lines, 1):
+            # Ignora linhas de comentário
+            stripped = line.strip()
+            if (stripped.startswith("//") or stripped.startswith("/*")
+                    or stripped.startswith("*") or stripped.startswith("#")
+                    or stripped.startswith("<!--")):
+                continue
+
+            line_lower = line.lower()
+
+            for val_normalized, token_names in value_to_tokens.items():
+                # Use word boundary matching to avoid substring false positives
+                # e.g., token value "16" should not match "216px"
+                # Build a pattern that matches the value with surrounding context
+                escaped_val = re.escape(val_normalized)
+                # Match value with word boundaries or common delimiters
+                boundary_pattern = re.compile(
+                    r"(?:^|[\s:=,;({\[])%s(?:$|[\s;,)}\]px%%rem em])" % escaped_val,
+                    re.IGNORECASE,
+                )
+                if boundary_pattern.search(line_lower):
+                    # Verifica se não está dentro de var() ou é definição do próprio token
+                    is_var_usage = re.search(r"var\(\s*" + re.escape(token_names[0]), line)
+                    is_definition = any(tn in line for tn in token_names)
+                    if not is_var_usage and not is_definition:
+                        hardcoded_matches.append({
+                            "file": filepath,
+                            "line": lineno,
+                            "token_name": ", ".join(token_names),
+                            "hardcoded_value": val_normalized,
+                        })
+
+    tokens_unused = set(tokens.keys()) - tokens_used
+    total = len(tokens)
+    coverage = (len(tokens_used) / total * 100) if total > 0 else 0.0
+
+    return {
+        "tokens_defined": total,
+        "tokens_used": tokens_used,
+        "tokens_unused": tokens_unused,
+        "hardcoded_matches": hardcoded_matches,
+        "coverage": coverage,
+    }
+
+
+def format_report(result, fmt="table"):
+    """Formata e imprime relatório de validação."""
+    if fmt == "json":
+        output = {
+            "tokens_defined": result["tokens_defined"],
+            "tokens_used": sorted(result["tokens_used"]),
+            "tokens_unused": sorted(result["tokens_unused"]),
+            "hardcoded_matches": result["hardcoded_matches"],
+            "coverage": round(result["coverage"], 1),
+        }
+        print(json.dumps(output, indent=2, ensure_ascii=False))
+        return
+
+    print(f"\n{'='*50}")
+    print(f"  RELATÓRIO DE TOKENS DE DESIGN")
+    print(f"{'='*50}\n")
+
+    total = result["tokens_defined"]
+    used = len(result["tokens_used"])
+    unused = len(result["tokens_unused"])
+
+    print(f"  Tokens definidos:  {total}")
+    print(f"  Tokens utilizados: {used}")
+    print(f"  Tokens não usados: {unused}")
+    print(f"  Cobertura:         {result['coverage']:.1f}%\n")
+
+    if result["tokens_unused"]:
+        print("  TOKENS NÃO UTILIZADOS:")
+        for token in sorted(result["tokens_unused"]):
+            print(f"    - {token}")
+        print()
+
+    if result["hardcoded_matches"]:
+        print(f"  VALORES HARDCODED ({len(result['hardcoded_matches'])} ocorrências):")
+        for match in result["hardcoded_matches"]:
+            print(f"    {match['file']}:{match['line']}")
+            print(f"      Valor: {match['hardcoded_value']}")
+            print(f"      Use:   var({match['token_name']})")
+        print()
+
+    if not result["tokens_unused"] and not result["hardcoded_matches"]:
+        print("  Todos os tokens estão sendo utilizados corretamente!\n")
+
+    print(f"{'='*50}\n")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Validador de uso de design tokens.",
+        epilog="""Exemplos:
+  python3 validate_tokens.py --design .hefesto/DESIGN.md --src src/
+  python3 validate_tokens.py --design .hefesto/DESIGN.md --src src/ -f json
+""",
+    )
+    parser.add_argument("--design", required=True, help="Caminho para DESIGN.md")
+    parser.add_argument("--src", required=True, help="Diretório fonte para escanear")
+    parser.add_argument(
+        "-f", "--format",
+        choices=["table", "json"],
+        default="table",
+        help="Formato de saída (padrão: table)",
+    )
+
+    args = parser.parse_args()
+
+    if not os.path.isfile(args.design):
+        print(f"Erro: DESIGN.md não encontrado: {args.design}", file=sys.stderr)
+        sys.exit(1)
+
+    if not os.path.isdir(args.src):
+        print(f"Erro: diretório fonte não encontrado: {args.src}", file=sys.stderr)
+        sys.exit(1)
+
+    result = validate_tokens(args.design, args.src)
+    format_report(result, args.format)
+
+    # Exit code não-zero se há tokens não usados ou valores hardcoded
+    if result["tokens_unused"] or result["hardcoded_matches"]:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/{commands/hefesto/init.md → skills/hefesto-init/SKILL.md}

@@ -1,5 +1,8 @@
 ---
-description: "Inicializa o Hefesto no projeto atual. Use /hefesto:init para criar a estrutura .hefesto/ e começar a organizar o desenvolvimento."
+name: hefesto-init
+description: "Inicializa o Hefesto no projeto atual. Use /hefesto-init para criar a estrutura .hefesto/ e começar a organizar o desenvolvimento."
+user-invocable: true
+disable-model-invocation: true
 ---
 
 # Hefesto Init
@@ -21,7 +24,8 @@ Inicializa a estrutura `.hefesto/` no projeto atual.
    ├── ROADMAP.md
    ├── STATE.md
    ├── config.json
-   └── features/
+   ├── features/
+   └── research/
    ```
 4. Preencher PROJECT.md com as respostas do usuário.
 5. Gerar STATE.md inicial com posição "Inicializando".
@@ -33,13 +37,34 @@ Inicializa a estrutura `.hefesto/` no projeto atual.
      "project": { "name": "", "language": "pt-BR" },
      "runtime": "claude",
      "feature": { "id_prefix": "FEAT", "counter": 0 },
+     "research": { "id_prefix": "RES", "counter": 0 },
      "lifecycle": { "auto_update_state": true }
    }
    ```
-8. Informar o usuário que o projeto foi inicializado e sugerir `/hefesto:new-feature` para criar a primeira feature.
+8. Informar o usuário que o projeto foi inicializado e sugerir `/hefesto-new-feature` para criar a primeira feature.
+9. Verificar se o MCP Context7 está configurado (checar se `.mcp.json` existe e contém `context7`). Se não estiver, sugerir a instalação:
+
+   ```
+   O Hefesto usa o Context7 para consultar documentação atualizada de bibliotecas
+   durante pesquisas. Para habilitar, adicione ao .mcp.json do projeto:
+   ```
+
+   ```json
+   {
+     "mcpServers": {
+       "context7": {
+         "command": "npx",
+         "args": ["-y", "@upstash/context7-mcp"]
+       }
+     }
+   }
+   ```
+
+   Se o usuário quiser instalar, criar ou atualizar o `.mcp.json` adicionando a entrada do Context7 (preservando outros MCPs existentes). Se não quiser, seguir sem — o Context7 é opcional.
 
 ## Notas
 
 - Todos os textos gerados devem ser em Português BR.
 - O config.json deve ser atualizado com o nome do projeto informado pelo usuário.
 - Se `.hefesto/` já existir e o usuário não quiser reinicializar, abortar sem modificar nada.
+- O Context7 é opcional mas recomendado — melhora a qualidade das pesquisas com docs versionados.

package/{commands/hefesto/new-feature.md → skills/hefesto-new-feature/SKILL.md}

@@ -1,5 +1,8 @@
 ---
-description: "Cria uma nova feature no Hefesto. Use /hefesto:new-feature para definir uma nova feature com visão, fluxo do usuário, requisitos e fases de implementação."
+name: hefesto-new-feature
+description: "Cria uma nova feature no Hefesto. Use /hefesto-new-feature para definir uma nova feature com visão, fluxo do usuário, requisitos e fases de implementação."
+user-invocable: true
+disable-model-invocation: true
 ---
 
 # Hefesto New Feature
@@ -8,7 +11,7 @@ Cria um novo documento de feature em `.hefesto/features/`.
 
 ## Pré-requisitos
 
-Verificar se `.hefesto/` existe. Se não existir, sugerir `/hefesto:init` primeiro.
+Verificar se `.hefesto/` existe. Se não existir, sugerir `/hefesto-init` primeiro.
 
 ## O que fazer
 

package/{commands/hefesto/update.md → skills/hefesto-update/SKILL.md}

@@ -1,5 +1,8 @@
 ---
-description: "Atualiza o Hefesto para a versão mais recente. Use /hefesto:update para atualizar commands, skills, hooks e templates sem perder o estado do projeto."
+name: hefesto-update
+description: "Atualiza o Hefesto para a versão mais recente. Use /hefesto-update para atualizar skills, hooks e templates sem perder o estado do projeto."
+user-invocable: true
+disable-model-invocation: true
 ---
 
 # Hefesto Update
@@ -8,7 +11,7 @@ Atualiza o toolkit Hefesto para a versão mais recente do npm.
 
 ## Pré-requisitos
 
-Verificar se `.hefesto/` existe. Se não existir, informar que o projeto não foi inicializado e sugerir `/hefesto:init`.
+Verificar se `.hefesto/` existe. Se não existir, informar que o projeto não foi inicializado e sugerir `/hefesto-init`.
 
 ## O que fazer
 
@@ -26,6 +29,6 @@ Verificar se `.hefesto/` existe. Se não existir, informar que o projeto não fo
 ## Notas
 
 - O installer preserva `.hefesto/` existente (PROJECT.md, STATE.md, ROADMAP.md, features/, config.json).
-- O que é atualizado: commands, skills, hooks, templates.
+- O que é atualizado: skills, hooks, templates.
 - Não usar `--global` a menos que o usuário peça explicitamente.
 - Se o usuário pedir para atualizar um runtime específico (ex: `--gemini`), passar a flag correspondente.