docs(core): README atualizado com estrutura real + gitignore + env.example

projetos/@pulse-libs/core/README.md

@@ -1,68 +1,111 @@
-# @pulse-libs/core
+# @pulse-libs/core — Biblioteca Universal Atomizada
 
-> Biblioteca universal componentizada — React · Vue · Hooks · Utils · Validators
-> Um único pacote. Todos os projetos.
+> **React · Hooks · Utils · Validators** em um único pacote  
+> `npm install @pulse-libs/core`
 
 ---
 
-## 📐 Estrutura atômica
+## 📐 Estrutura real do projeto
 
 ```
 @pulse-libs/core
-├── types/         Tipos TypeScript compartilhados (zero deps)
-├── utils/         Funções puras — date, str, num, classnames, debounce, throttle
-├── validators/    Schemas Zod reutilizáveis (email, password, uuid, phone)
-├── hooks/         React hooks — useToggle, useAsync, useDebounce, useLocalStorage
-├── components/    Componentes atômicos React — Button, Input, Alert, Card, Spinner
-├── composable-vue/ Composables Vue 3
-├── composables/   Composables genéricos (agnósticos de framework)
-├── lib/           Helpers third-party (sem duplicar lógica)
-└── constants/     Constantes comuns (status codes, mensagens, etc)
+├── src/
+│   ├── types/         → Result / AsyncState / Paginated / SortConfig  (zero deps)
+│   ├── utils/         → date, str, num, cn, debounce, throttle, storage, arr, obj  (zero deps)
+│   ├── validators/    → Zod schemas: email, password, uuid, url, phone, CPF/CNPJ
+│   ├── hooks/         → useToggle, useAsync, useDebounce, useLocalStorage, useMedia, useInterval, useOnClickOutside, useClipboard, useFetch
+│   ├── components/    → Button, Input, Alert, Card (+Header/Title/Body), Spinner  (React)
+│   └── index.ts       → barrel export principal
+├── tests/             → vitest + jsdom — 57 testes, 100% passando
+├── dist/              → ESM + CJS + DTS + sourcemaps (gerado por tsup v8)
+├── Dockerfile         → multi-stage Node 20 Alpine
+├── __docs__/          → guias de deploy, docker, arquitetura
+└── package.json       → sub-exports por camada
 ```
 
-## 🚀 Instalação
-
-```bash
-npm install @pulse-libs/core zod react vue
-```
+## 📦 Imports por camada
 
 ```tsx
-// React — utilitários + componentes
-import { Button, Input, useAsync, date, cn } from '@pulse-libs/core';
+// ── Root barrel
+import { Button, useAsync, date, cn } from '@pulse-libs/core';
 
-// Validadores
-import { emailSchema, passwordSchema, safeParse } from '@pulse-libs/core/validators';
-
-// Vue — composables
-import { useToggle, useLocalStorage } from '@pulse-libs/core/vue';
-```
-
-## 📦 Sub-exports
-
-```ts
-import { Button }    from '@pulse-libs/core/react';
-import { useFetch }  from '@pulse-libs/core/hooks';
-import { cn, date }  from '@pulse-libs/core/utils';
+// ── Sub-exports (tree-shakeable)
+import { Button, Input, Alert }       from '@pulse-libs/core/components';
+import { useToggle, useDebounce }      from '@pulse-libs/core/hooks';
+import { cn, date, str, num, storage } from '@pulse-libs/core/utils';
+import { emailSchema, safeParse }      from '@pulse-libs/core/validators';
+import type { Result, AsyncState }     from '@pulse-libs/core/types';
 ```
 
 ## 🏗️ Filosofia atômica
 
-| Camada | Exemplo | Depende de |
-|--------|---------|------------|
-| **Utils** | `cn()`, `debounce()`, `date.format()` | zero |
-| **Types** | `Result<T>`, `AsyncState<T>` | zero |
-| **Validators** | `emailSchema`, `uuidSchema` | utils, types, zod |
-| **Hooks** | `useAsync()`, `useDebounce()` | utils, types, react |
-| **Components** | `Button`, `Input`, `Alert` | utils, validators |
+Uma camada **nunca importa de uma camada de nível inferior**:
 
-> **Regra de ouro**: uma camada nunca importa de uma camada de nível inferior.
-> Utils não sabe que Hooks existem. Hooks não sabe que Components existem.
+```
+utils   ← zero deps
+types   ← zero deps
+validators ← usa utils, types, zod
+hooks   ← usa utils, types, react
+components ← usa utils, validators
+```
+
+### Convenções de código
+
+| Regra | Por quê |
+|-------|---------|
+| `className` sempre no topo dos props | Tailwind merge via `cn()` |
+| `...rest` sempre por último | Não mata props nativas |
+| Funções puras em `utils/` | Testáveis sem setup |
+| Schema Zod é a **única** fonte de verdade | Sem validação duplicada |
+| DTS arquivos declarados (`--dts`) | Imports no TS dos consumidores |
+| `flat(2)` nunca `flat(Infinity)` | Quebra DTS generate |
 
 ## 🔄 Versionamento
 
-- `1.0.0-beta.x` — desenvolvimento, API pode mudar
-- `1.0.0`        — primeiro release estável, API congelada
+| Fase | Tag | Significado |
+|------|-----|-------------|
+| alpha | `1.0.0-alpha.x` | API instável |
+| beta | `1.0.0-beta.x` | feature-complete, API pode mudar |
+| stable | `1.0.0` | API congelada, sem breaking em minor |
+
+## 🚀 Comandos
+
+```bash
+npm run build        # tsup ESM+CJS+DTS+sourcemaps
+npm run build:esm    # ESM only
+npm run build:cjs    # CJS only
+npm test             # vitest run (57 testes)
+npm test:w           # vitest watch mode
+npm run coverage     # relatorio de cobertura
+npm run typecheck    # tsc --noEmit
+npm run lint         # eslint (se configurado)
+npm run dev          # tsup --watch
+npm run clean        # rm -rf dist coverage .tsup
+npm run release      # bumpp + git push --follow-tags
+```
+
+## 🐳 Docker
+
+```bash
+# Build image
+docker build -t pulse-libs/core:1.0.0-beta.1 .
+
+# Ou com docker-compose
+docker compose build
+
+# Test local
+docker compose run core npm test
+```
+
+## 📚 Documentação adicional
+
+- [`__docs__/docker/build-guide.md`](__docs__/docker/build-guide.md) — Guia de build e publish Docker
+- [`__docs__/docker/architecture.md`](__docs__/docker/architecture.md) — Arquitetura da biblioteca
 
 ## 🤝 Contribuir
 
-Ver [CONTRIBUTING.md](CONTRIBUTING.md).
+- Issues com tag `[bug]`, `[feat]`, `[docs]`
+- PRs devem Rodar `npm test` + `npm run typecheck` antes
+- Cada camada nova precisa de pelo menos 1 teste unitário
+- Breaking changes só em major version (`2.0.0`, `3.0.0`, …)
+- Sem duplicação de lógica — extrair para utils antes de adicionar