@lugom.io/hefesto 0.2.0 → 1.0.0

package/skills/hefesto-init/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: hefesto-init
+description: >
+  Inicializa um projeto com Hefesto. Dois modos: (1) projeto novo — scaffold com stack
+  pré-definida (web/cli/api/mobile); (2) projeto existente — analisa codebase, cria .hefesto/
+  e gera CLAUDE.md.
+  Usar com: /hefesto-init.
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Hefesto Init
+
+Inicializa um projeto com a estrutura `.hefesto/`, gera `CLAUDE.md` e, opcionalmente, faz scaffold do código base. Para projetos existentes, faz uma varredura automática do codebase para detectar stack, plataforma, convenções e comandos.
+
+## Fluxo
+
+### Fase 1 — Verificar estado
+
+1. Verificar se `.hefesto/` já existe (`Bash: ls .hefesto/ 2>/dev/null`)
+2. Se existir:
+   - Ler `.hefesto/PROJECT.md` — se contém `{{PROJECT_NAME}}` → install fresco, prosseguir
+   - Senão → já configurado. Seletor: **Reinicializar** (apaga e recria, avisa sobre features existentes) / **Atualizar** (re-varredura, preserva features/) / **Cancelar**
+3. Se não existir → Fase 2
+
+### Fase 2 — Tipo de projeto
+
+Seletor: **Novo** → Fase 3A | **Existente** → Fase 3B.1
+
+### Fase 3A — Scaffold de projeto novo
+
+1. Seletor de **plataforma**:
+   - `web` — Next.js + TypeScript + TailwindCSS + shadcn/ui
+   - `cli` — Node.js + TypeScript + ES Modules
+   - `api` — Node.js + TypeScript + Fastify
+   - `mobile` — React Native + Expo + NativeWind
+
+2. Ler `references/{plataforma}.md` (relativo a esta skill)
+3. Executar scaffold conforme a referência
+4. Coletar do usuário: **Nome** (sugerir dir atual), **Descrição** (2-3 frases), **Valor central**, **Prazo/restrições**
+
+### Fase 3B.1 — Varredura do codebase
+
+Análise rápida (~10 reads) para detectar informações do projeto:
+
+**Passo 1 — Manifesto**: Glob por `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, `pom.xml`, `pubspec.yaml`. Se nenhum → modo manual (Fase 3B.2).
+
+**Passo 2 — Identidade**: Nome, descrição, dependências, scripts do manifesto. Fallback: README.md (primeiras 30 linhas).
+
+**Passo 3 — Linguagem** (por prioridade): tsconfig.json → TypeScript | jsconfig.json/package.json → JavaScript | pyproject.toml/requirements.txt → Python | go.mod → Go | Cargo.toml → Rust | Gemfile → Ruby | pubspec.yaml → Dart. Se ambíguo, contar arquivos por extensão.
+
+**Passo 4 — Plataforma**: Inferir das dependências — frameworks web → `web`, react-native/expo → `mobile`, express/fastify/flask/etc sem frontend → `api`, campo bin → `cli`, exports sem bin/web → `library`, frontend + backend → `fullstack`, nenhum → `other`.
+
+**Passo 5 — Monorepo**: workspaces em package.json, lerna.json, nx.json, turbo.json, pnpm-workspace.yaml.
+
+**Passo 6 — Comandos**: Extrair de package.json scripts (dev, build, test, lint, format) ou Makefile.
+
+**Passo 7 — Arquitetura**: Listar dirs em `src/` — features/modules/domains → feature-based | controllers/services/models → layered | app/pages → file-based routing. Detectar formatação: Prettier, ESLint, Biome, EditorConfig.
+
+### Fase 3B.2 — Confirmação
+
+Apresentar resultado da varredura em tabela (Campo | Detectado | Fonte). O usuário confirma ou ajusta.
+
+Perguntar apenas o não-detectável: **Valor central** (sempre), **Prazo** (sempre), **Descrição** (se não detectada). Se varredura pulada, coletar tudo manualmente.
+
+### Fase 4 — Criar estrutura .hefesto/
+
+Criar os artefatos listados em `/hefesto-context` (seção "Estrutura `.hefesto/`"): `PROJECT.md`, `STATE.md`, `config.json`, `features/`, `research/`.
+
+### Fase 5 — Preencher arquivos
+
+Ler os templates em `.hefesto/templates/TPL-*.md` (já copiados pelo instalador) e substituir os placeholders `{{...}}` com os dados coletados.
+
+**PROJECT.md**: Dados do projeto, valor central, stack, convenções. Para projetos novos, copiar convenções do reference file. Para existentes, gerar da varredura. Preencher `{{RECIPES}}` com a seção "Receitas" do reference file do preset — lista curta com nome e quando usar cada receita.
+
+**STATE.md**: Data e foco inicial.
+
+**config.json**: Atualizar seção `project` (name, description, platform, lang, monorepo). Valores vêm do preset (novos) ou da varredura (existentes). Não alterar demais seções.
+
+**verification.commands**: Preencher com comandos detectados (test, lint, typecheck). Para projetos novos, usar padrão do preset. Se nada detectado, deixar vazio com `auto_detect: true`.
+
+### Fase 5B — Gerar CLAUDE.md
+
+Ler template `TPL-CLAUDE.md` e substituir placeholders com dados coletados.
+
+Se CLAUDE.md existir: seletor **Substituir** / **Mesclar** (adicionar seção Hefesto) / **Pular**.
+
+Para projetos novos: usar dados do reference file. Para existentes: usar resultado da varredura.
+
+Princípios: conciso, sem repetição do PROJECT.md, sem obviedades, comandos acionáveis.
+
+### Fase 6 — MCP Context7
+
+Se o projeto usa dependências externas (frameworks, bibliotecas, SDKs): verificar `.mcp.json` para `context7`. Se não existir, sugerir configuração para o usuário. Se o projeto não tem dependências externas, pular.
+
+### Fase 7 — Resultado
+
+Informar o que foi criado. Sugerir `/hefesto-new-feature`. Se plataforma `web` ou `mobile`, sugerir também `/hefesto-design` para definir o contrato visual.
+
+## Notas
+
+- Se usuário disser "decide você", fazer escolha razoável e justificar
+- **Atualizar**: não executar scaffold, apenas re-varredura + update dos arquivos .hefesto/
+- Varredura deve ser rápida (~10 reads)
+- CLAUDE.md gerado deve ser conciso — apenas o não derivável do código

package/skills/hefesto-init/references/api.md

@@ -0,0 +1,116 @@
+# Preset: API
+
+## Stack
+
+- Node.js + TypeScript
+- Fastify
+- ES Modules
+- pnpm (package manager)
+
+## Scaffold
+
+### 1. Inicializar projeto
+
+```bash
+pnpm init
+```
+
+### 2. Configurar package.json
+
+Editar o `package.json` gerado:
+
+- Adicionar `"type": "module"`
+- Adicionar scripts:
+  ```json
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js"
+  }
+  ```
+
+### 3. Instalar dependências
+
+```bash
+pnpm add fastify
+pnpm add -D typescript @types/node tsx
+```
+
+### 4. Criar tsconfig.json
+
+Criar `tsconfig.json` com:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### 5. Criar estrutura de diretórios e arquivos
+
+```
+src/
+├── server.ts
+└── routes/
+    └── health.ts
+```
+
+### 6. Criar src/server.ts
+
+```typescript
+import Fastify from 'fastify';
+import { healthRoutes } from './routes/health.js';
+
+const app = Fastify({ logger: true });
+
+app.register(healthRoutes);
+
+app.listen({ port: 3000, host: '0.0.0.0' }, (err) => {
+  if (err) {
+    app.log.error(err);
+    process.exit(1);
+  }
+});
+```
+
+### 7. Criar src/routes/health.ts
+
+```typescript
+import { FastifyInstance } from 'fastify';
+
+export async function healthRoutes(app: FastifyInstance) {
+  app.get('/health', async () => {
+    return { status: 'ok' };
+  });
+}
+```
+
+### 8. Estrutura resultante esperada
+
+```
+src/
+├── server.ts
+└── routes/
+    └── health.ts
+tsconfig.json
+package.json
+```
+
+## config.json
+
+- platform: "api"
+- lang: "typescript"
+- monorepo: false

package/skills/hefesto-init/references/cli.md

@@ -0,0 +1,91 @@
+# Preset: CLI
+
+## Stack
+
+- Node.js + TypeScript
+- ES Modules
+- pnpm (package manager)
+
+## Scaffold
+
+### 1. Inicializar projeto
+
+```bash
+pnpm init
+```
+
+### 2. Configurar package.json
+
+Editar o `package.json` gerado:
+
+- Adicionar `"type": "module"`
+- Adicionar campo `"bin"`: `{ "<nome-do-projeto>": "./dist/cli.js" }`
+- Adicionar scripts:
+  ```json
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js"
+  }
+  ```
+
+### 3. Instalar TypeScript
+
+```bash
+pnpm add -D typescript @types/node
+```
+
+### 4. Criar tsconfig.json
+
+Criar `tsconfig.json` com:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### 5. Criar estrutura de diretórios e arquivos
+
+```
+src/
+└── cli.ts              ← entry point
+```
+
+### 6. Criar src/cli.ts
+
+```typescript
+#!/usr/bin/env node
+
+console.log('<nome-do-projeto> v0.1.0');
+```
+
+Substituir `<nome-do-projeto>` pelo nome real do projeto.
+
+### 7. Estrutura resultante esperada
+
+```
+src/
+└── cli.ts
+tsconfig.json
+package.json
+```
+
+## config.json
+
+- platform: "cli"
+- lang: "typescript"
+- monorepo: false

package/skills/hefesto-init/references/mobile.md

@@ -0,0 +1,69 @@
+# Preset: Mobile
+
+## Stack
+
+- React Native + Expo + TypeScript
+- Expo Router (navegação file-based)
+- NativeWind (TailwindCSS para React Native)
+
+## Scaffold
+
+### 1. Criar projeto Expo
+
+```bash
+npx create-expo-app@latest . --template tabs
+```
+
+Se o diretório não estiver vazio, apresentar ao usuário via seletor interativo: **Criar num subdiretório** / **Limpar primeiro**.
+
+### 2. Instalar NativeWind
+
+```bash
+npx expo install nativewind tailwindcss
+```
+
+### 3. Configurar TailwindCSS
+
+Criar `tailwind.config.js`:
+
+```javascript
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ['./app/**/*.{ts,tsx}', './components/**/*.{ts,tsx}'],
+  presets: [require('nativewind/preset')],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};
+```
+
+Adicionar o plugin do NativeWind no `babel.config.js` (se existir) ou em `metro.config.js` conforme a documentação do NativeWind para a versão instalada.
+
+### 4. Limpar boilerplate
+
+- Simplificar as tabs de exemplo — manter a estrutura mas substituir o conteúdo.
+- Substituir o conteúdo da tab Home por uma tela limpa com o nome do projeto centralizado.
+- Remover assets de exemplo desnecessários.
+
+### 5. Estrutura resultante esperada
+
+```
+app/
+├── (tabs)/
+│   ├── index.tsx         ← Home limpa com nome do projeto
+│   ├── _layout.tsx       ← Tab layout
+│   └── explore.tsx       ← Tab secundária
+├── _layout.tsx           ← Root layout
+└── +not-found.tsx
+assets/
+components/
+constants/
+hooks/
+```
+
+## config.json
+
+- platform: "mobile"
+- lang: "typescript"
+- monorepo: false

package/skills/hefesto-init/references/web.md

@@ -0,0 +1,246 @@
+# Preset: Web
+
+## Stack
+
+- Next.js (App Router) + TypeScript
+- TailwindCSS + shadcn/ui
+- Vitest + Playwright
+- ESLint + Prettier
+- T3 Env + Zod
+- pnpm (package manager)
+
+## Scaffold
+
+### 1. Criar projeto Next.js
+
+```bash
+pnpx create-next-app@latest . --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --turbopack --yes
+```
+
+Após o scaffold, deletar arquivos genéricos gerados: `rm -f CLAUDE.md AGENTS.md`
+
+**Diretório não vazio:** se `.hefesto/` ou `package.json` já existem, criar num subdiretório temporário e mover:
+
+```bash
+pnpx create-next-app@latest .tmp-scaffold --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --turbopack --yes
+mv .tmp-scaffold/* . && mv .tmp-scaffold/.gitignore . 2>/dev/null && mv .tmp-scaffold/.eslintrc* . 2>/dev/null
+rmdir .tmp-scaffold
+rm -f CLAUDE.md AGENTS.md
+```
+
+### 2. shadcn/ui
+
+```bash
+pnpx shadcn@latest init -d
+```
+
+### 3. Prettier
+
+```bash
+pnpm add -D prettier prettier-plugin-tailwindcss eslint-config-prettier
+```
+
+Criar `.prettierrc` (semi, singleQuote, trailingComma all, plugin tailwindcss). Criar `.prettierignore` (node_modules, .next, dist, coverage, .claude, .hefesto). Adicionar `eslint-config-prettier` ao ESLint config.
+
+Scripts: `format`, `format:check`.
+
+### 4. Vitest
+
+```bash
+pnpm add -D vitest @vitejs/plugin-react @testing-library/react @testing-library/dom @testing-library/user-event @testing-library/jest-dom jsdom vite-tsconfig-paths
+```
+
+Criar `vitest.config.ts` (jsdom, react plugin, tsconfigPaths, setup em `tests/setup.ts`, include `src/**/*.test.*` e `tests/unit/**`). Criar `tests/setup.ts` com import de `@testing-library/jest-dom/vitest`.
+
+Scripts: `test`, `test:watch`, `test:coverage`.
+
+### 5. Playwright
+
+```bash
+pnpm add -D @playwright/test
+pnpx playwright install --with-deps chromium
+```
+
+Criar `playwright.config.ts` (testDir `tests/e2e`, baseURL localhost:3000, webServer com `pnpm dev`).
+
+Script: `test:e2e`.
+
+### 6. T3 Env + Zod
+
+```bash
+pnpm add @t3-oss/env-nextjs zod
+```
+
+Criar `src/lib/env.ts` com `createEnv` (server: NODE_ENV, client: vazio). Importar `./src/lib/env.ts` no topo de `next.config.ts`. Criar `.env.example`. Adicionar `.env`, `.env.local`, `.env.production` ao `.gitignore`.
+
+### 7. Limpar boilerplate
+
+- `src/app/page.tsx` → página limpa com `<h1>` do nome do projeto
+- `src/app/globals.css` → apenas imports Tailwind + variáveis shadcn
+- Remover assets padrão em `public/` (next.svg, vercel.svg)
+- Simplificar `src/app/layout.tsx`
+
+### 8. Criar estrutura feature-based
+
+```bash
+mkdir -p src/features src/hooks src/services src/types tests/unit tests/e2e
+```
+
+Criar `.gitkeep` nos diretórios vazios.
+
+### 9. Formatação inicial
+
+```bash
+pnpm format
+```
+
+---
+
+## Arquitetura e Convenções
+
+### Feature-based
+
+Código organizado por domínio em `src/features/`. Cada feature:
+
+```
+src/features/<nome>/
+├── components/     ← componentes da feature
+├── hooks/          ← hooks da feature
+├── services/       ← lógica de negócio e chamadas de API
+├── types/          ← tipos e interfaces
+└── index.ts        ← barrel export (API pública)
+```
+
+Compartilhado entre features fica em `src/` raiz: `components/`, `components/ui/` (shadcn), `hooks/`, `services/`, `types/`, `lib/`.
+
+### Princípios
+
+1. **Features não importam de outras features.** Código compartilhado sobe para `src/`.
+2. **`src/app/` só contém rotas e layouts.** Lógica fica em `src/features/`.
+3. **Barrel exports** — importar do índice: `import { LoginForm } from '@/features/auth'`.
+4. **Sem `any`** — usar `unknown` e narrowing.
+5. **Validação nas bordas** — inputs de usuário e APIs externas com Zod.
+6. **Env validado** — usar `env` de `@/lib/env`, nunca `process.env` direto.
+
+### Naming
+
+| Elemento    | Convenção          | Exemplo                |
+| ----------- | ------------------ | ---------------------- |
+| Componentes | PascalCase         | `ProductCard.tsx`      |
+| Hooks       | useCamelCase       | `useProducts.ts`       |
+| Serviços    | camelCase.service  | `auth.service.ts`      |
+| Tipos       | PascalCase         | `User`, `AuthResult`   |
+| Constantes  | SCREAMING_SNAKE    | `MAX_ITEMS_PER_PAGE`   |
+| Testes      | .test.ts/.test.tsx | `auth.service.test.ts` |
+
+### Testes
+
+- **Co-localizados** (`src/**/*.test.ts`) — lógica de negócio. Ficam ao lado do arquivo.
+- **De feature** (`tests/unit/`) — testes criados pelo Argos para validar requisitos. Nome: `feat-NNN-slug.test.ts`.
+- **E2E** (`tests/e2e/`) — fluxos críticos com Playwright.
+
+### Next.js 16 — `proxy.ts`
+
+No Next.js 16, `middleware.ts` foi substituído por `proxy.ts` (runtime Node.js em vez de Edge). Função exportada: `proxy` em vez de `middleware`. Para migrar: `npx @next/codemod@canary middleware-to-proxy .`
+
+Para proteção de rotas, preferir Server Components com `redirect()`.
+
+---
+
+## Receitas
+
+Padrões prontos para adotar conforme a feature precisar. **Não são instaladas no scaffold** — usar quando o projeto demandar.
+
+### Data Fetching — TanStack Query
+
+**Quando:** a feature precisa buscar, cachear ou sincronizar dados do servidor.
+
+```bash
+pnpm add @tanstack/react-query @tanstack/react-query-devtools
+```
+
+Setup: criar `src/lib/query-client.ts` com `QueryClient` configurado (staleTime, gcTime). Criar `src/components/providers.tsx` com `QueryClientProvider` wrapping children + `ReactQueryDevtools` em dev. Adicionar o provider no `layout.tsx` (como Client Component).
+
+Pattern de uso em features:
+
+```
+src/features/products/
+├── hooks/
+│   └── use-products.ts    ← useQuery + queryKey + fetch function
+├── services/
+│   └── products.service.ts ← fetch functions puras (sem hooks)
+```
+
+Hooks chamam services. Services são funções puras testáveis. Query keys seguem padrão `[feature, ...params]`.
+
+### Formulários — React Hook Form + Zod
+
+**Quando:** a feature tem formulários com validação.
+
+```bash
+pnpm add react-hook-form @hookform/resolvers
+```
+
+Zod já está na stack. Usar `zodResolver` com `useForm`. Integrar com componentes `Form` do shadcn/ui (`npx shadcn@latest add form`).
+
+Pattern: schema Zod define a validação, `useForm` gerencia o state, shadcn/ui `FormField` renderiza.
+
+### Estado Global — Zustand
+
+**Quando:** estado precisa ser compartilhado entre features sem prop drilling. Preferir para estado de UI (sidebar aberta, tema, filtros). Para dados do servidor, usar TanStack Query.
+
+```bash
+pnpm add zustand
+```
+
+Pattern: um store por domínio em `src/features/<nome>/stores/`. Stores exportam hooks (`useCartStore`). Usar slices para stores complexas.
+
+### Autenticação — Better Auth
+
+**Quando:** a feature precisa de login, registro, sessões ou proteção de rotas.
+
+```bash
+pnpm add better-auth
+```
+
+Setup: criar `src/lib/auth.ts` (server) com `betterAuth()` configurando database adapter e providers (email/password, Google, GitHub). Criar `src/lib/auth-client.ts` com `createAuthClient()`. Criar API route em `src/app/api/auth/[...all]/route.ts`.
+
+Plugins úteis: `twoFactor()`, `magicLink()`, `organization()`.
+
+Pattern de proteção: Server Components usam `auth.api.getSession()` + `redirect()`. Client Components usam `authClient.useSession()`.
+
+### Banco de Dados — Drizzle ORM
+
+**Quando:** a feature precisa persistir dados.
+
+```bash
+pnpm add drizzle-orm postgres
+pnpm add -D drizzle-kit
+```
+
+Setup: criar `src/db/index.ts` (connection com `postgres` driver). Criar `src/db/schema/` com schemas por domínio. Criar `drizzle.config.ts` apontando para o schema e connection string via `env.ts`, com `out: './src/db/migrations'`.
+
+Estrutura:
+
+```
+src/db/
+├── index.ts          ← connection + export do db
+├── schema/
+│   ├── index.ts      ← re-export de todos os schemas
+│   └── users.ts
+└── migrations/       ← geradas pelo drizzle-kit (out: './src/db/migrations')
+```
+
+Adicionar `DATABASE_URL` ao T3 Env (`src/lib/env.ts`) e `.env.example`.
+
+Scripts: `db:generate` (`drizzle-kit generate`), `db:migrate` (`drizzle-kit migrate`), `db:studio` (`drizzle-kit studio`).
+
+Pattern: schemas em `src/db/schema/<dominio>.ts`, queries em `src/features/<nome>/services/`.
+
+---
+
+## config.json
+
+- platform: "web"
+- lang: "typescript"
+- monorepo: false