From 154e233d6d5c188c8ec670cc920621f974f5be2e Mon Sep 17 00:00:00 2001 From: pulse-agent Date: Tue, 19 May 2026 21:47:32 -0300 Subject: [PATCH] docs(core): README atualizado com estrutura real + gitignore + env.example --- projetos/@pulse-libs/core/.env.example | 14 +++ projetos/@pulse-libs/core/.gitignore | 35 +++++++ projetos/@pulse-libs/core/README.md | 133 ++++++++++++++++--------- 3 files changed, 137 insertions(+), 45 deletions(-) create mode 100644 projetos/@pulse-libs/core/.env.example create mode 100644 projetos/@pulse-libs/core/.gitignore diff --git a/projetos/@pulse-libs/core/.env.example b/projetos/@pulse-libs/core/.env.example new file mode 100644 index 0000000..fc04e1e --- /dev/null +++ b/projetos/@pulse-libs/core/.env.example @@ -0,0 +1,14 @@ +# @pulse-libs/core — ambiente de desenvolvimento +# Copiar como .env e preencher os valores + +# NPM Registry (para publish) +NPM_TOKEN= # token de publish no registry.npmjs.org + +# CI/CD +NODE_ENV=production +SKIP_ZOD=true # skip validador snapshot em CI se necessário + +# GitHub Actions (auto-preenchido pelo runner) +GITHUB_TOKEN= +GITHUB_REPOSITORY= +NODE_VERSION=20 diff --git a/projetos/@pulse-libs/core/.gitignore b/projetos/@pulse-libs/core/.gitignore new file mode 100644 index 0000000..6211f83 --- /dev/null +++ b/projetos/@pulse-libs/core/.gitignore @@ -0,0 +1,35 @@ +# @pulse-libs/core — gitignore +node_modules/ +dist/ +coverage/ +.tsup/**/*.tmp* + +# Testes +.vitest/ +coverage/ + +# Env +.env +.env.* +!.env.example + +# OS +.DS_Store +Thumbs.db + +# Editor +.idea/ +.vscode/ +*.swp +*.swo + +# Logs +*.log +npm-debug.log* + +# Git +.git/ +!.gitignore + +# CI/temp +.github/ diff --git a/projetos/@pulse-libs/core/README.md b/projetos/@pulse-libs/core/README.md index 546d12b..54af217 100644 --- a/projetos/@pulse-libs/core/README.md +++ b/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`, `AsyncState` | 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