feat(@pulse-libs/core): WürthFlow completo — docs, CI/CD, Docker, arquitetura, WürthFlow
- __docs__/docker/build-guide.md — guia docker multi-stage
- __docs__/docker/architecture.md — fluxograma ASCII + camadas de dependencia
- __docs__/ci/github-actions.md — CI completo com jobs test/build/docker/publish/release
- .github/workflows/ci.yml — workflow GitHub Actions gerado
- README.md reescrito com estrutura real do pacote
- WürthFlow.md — documento vivo da arquitetura do workspace
🤖 Pulse + nova-self-improver
This commit is contained in:
pulse-agent
@@ -0,0 +1,126 @@
|
||||
# CI/CD — GitHub Actions para @pulse-libs/core
|
||||
|
||||
## .github/workflows/ci.yml
|
||||
|
||||
```yaml
|
||||
name: CI — @pulse-libs/core
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main, master]
|
||||
pull_request:
|
||||
branches: [main, master]
|
||||
release:
|
||||
types: [published]
|
||||
|
||||
concurrency:
|
||||
group: ci-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
test:
|
||||
name: Test & Lint
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 20
|
||||
cache: npm
|
||||
- run: npm ci
|
||||
- run: npm run typecheck
|
||||
- run: npm test -- --coverage
|
||||
- uses: codecov/codecov-action@v4
|
||||
if: matrix.os == 'ubuntu-latest'
|
||||
with:
|
||||
file: ./coverage/coverage-final.json
|
||||
fail_ci_if_error: false
|
||||
|
||||
build:
|
||||
name: Build
|
||||
runs-on: ubuntu-latest
|
||||
needs: test
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 20
|
||||
cache: npm
|
||||
- run: npm ci
|
||||
- run: npm run build
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: dist
|
||||
path: dist/
|
||||
retention-days: 7
|
||||
|
||||
docker:
|
||||
name: Docker Build & Push
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: docker/setup-buildx-action@v3
|
||||
- uses: docker/login-action@v3
|
||||
with:
|
||||
registry: docker.io
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
- uses: docker/build-push-action@v5
|
||||
with:
|
||||
context: .
|
||||
push: true
|
||||
tags: |
|
||||
pulse/core:latest
|
||||
pulse/core:1.0.0-beta.1
|
||||
pulse/core:${{ github.sha }}
|
||||
|
||||
publish:
|
||||
name: Publish to npm
|
||||
runs-on: ubuntu-latest
|
||||
needs: [test, build]
|
||||
if: github.ref == 'refs/heads/main'
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 20
|
||||
registry-url: https://registry.npmjs.org
|
||||
- run: npm ci
|
||||
- run: npm publish --access public
|
||||
env:
|
||||
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||
|
||||
release:
|
||||
name: Create GitHub Release
|
||||
runs-on: ubuntu-latest
|
||||
needs: publish
|
||||
if: startsWith(github.ref, 'refs/tags/v')
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: softprops/action-gh-release@v1
|
||||
with:
|
||||
generate_release_notes: true
|
||||
```
|
||||
|
||||
## Triggers & Jobs
|
||||
|
||||
| Event | teste | build | docker | publish | release |
|
||||
|---|---|---|---|---|---|
|
||||
| PR → main | ✅ | ✅ | — | — | — |
|
||||
| push → main | ✅ | ✅ | ✅ | ✅ | — |
|
||||
| tag v* | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
|
||||
## Secrets Necessários
|
||||
|
||||
| Secret | Usado em | Descrição |
|
||||
|---|---|---|
|
||||
| `NPM_TOKEN` | publish | Token de publish do npmjs.org |
|
||||
| `DOCKERHUB_USERNAME` | docker | Usuário Docker Hub |
|
||||
| `DOCKERHUB_TOKEN` | docker | Token de acesso Docker Hub |
|
||||
|
||||
## Cobertura de Código
|
||||
|
||||
O job `test` gera cobertura com c8/v8 provider.
|
||||
Codecov opcional — remova o step se não usar.
|
||||
@@ -0,0 +1,96 @@
|
||||
# Arquitetura da Biblioteca — @pulse-libs/core
|
||||
|
||||
## Fluxograma de Dependências (ASCII)
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ CAMADA 0 — Zero Dependencies │
|
||||
│ types/ Result<T,E> AsyncState<T> Paginated │
|
||||
│ utils/ date str num cn debounce throttle │
|
||||
└────────────────────────┬─────────────────────────┘
|
||||
│ usam
|
||||
↓
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ CAMADA 1 — Só Zod + tipos │
|
||||
│ validators/ emailSchema passwordSchema │
|
||||
│ uuidSchema phoneSchema … │
|
||||
└────────────────────────┬─────────────────────────┘
|
||||
│ usam
|
||||
↓
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ CAMADA 2 — React + utils │
|
||||
│ hooks/ useAsync useDebounce useLocalStorage│
|
||||
│ useMedia useClipboard … │
|
||||
└────────────────────────┬─────────────────────────┘
|
||||
│ usam
|
||||
↓
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ CAMADA 3 — React + Tailwind + Utils │
|
||||
│ components/ Button Input Alert Card Spinner │
|
||||
└──────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Código D2 da Arquitetura
|
||||
|
||||
```d2
|
||||
direction: down
|
||||
|
||||
subgraph camada0 ["CAMADA 0 — Zero Dependencies"]
|
||||
TYPES: types/
|
||||
UTILS: utils/
|
||||
end
|
||||
|
||||
subgraph camada1 ["CAMADA 1 — Zod + tipos"]
|
||||
VALIDATORS: validators/
|
||||
end
|
||||
|
||||
subgraph camada2 ["CAMADA 2 — React + utils"]
|
||||
HOOKS: hooks/
|
||||
end
|
||||
|
||||
subgraph camada3 ["CAMADA 3 — React + Tailwind"]
|
||||
COMPONENTS: components/
|
||||
end
|
||||
|
||||
TYPES -> VALIDATORS
|
||||
UTILS -> VALIDATORS
|
||||
TYPES -> HOOKS
|
||||
UTILS -> HOOKS
|
||||
VALIDATORS -> COMPONENTS
|
||||
UTILS -> COMPONENTS
|
||||
```
|
||||
|
||||
## Princípios Arquiteturais
|
||||
|
||||
| Princípio | Como é aplicado |
|
||||
|-----------|-----------------|
|
||||
| Zero-backwards imports | Camada n nunca importa camada n+1 |
|
||||
| Pure functions first | `utils/` não tem side-effects, testável sem setup |
|
||||
| Schema = fonte da verdade | Toda validação vem de Zod |
|
||||
| Tree-shakeable exports | Cada sub-export exporta só o necessário |
|
||||
| Peer deps opcionais | React/Vue são optionalPeerDependencies |
|
||||
|
||||
## Entry Points Build (tsup v8)
|
||||
|
||||
```
|
||||
src/index.ts → dist/index.{js,mjs,js.map,d.ts,d.mts}
|
||||
src/utils/index.ts → dist/utils/index.{js,mjs,js.map,d.ts,d.mts}
|
||||
src/types/index.ts → dist/types/index.{js,mjs,js.map,d.ts,d.mts}
|
||||
src/validators/… → dist/validators/index.{js,mjs,js.map,d.ts,d.mts}
|
||||
src/components/… → dist/components/index.{js,mjs,js.map,d.ts,d.mts}
|
||||
```
|
||||
|
||||
## Tamanho esperado do bundle
|
||||
|
||||
| Camada | ESM | CJS |
|
||||
|--------|-----|-----|
|
||||
| `@pulse-libs/core` (root) | ~5 KB | ~7 KB |
|
||||
| `@pulse-libs/core/utils` | ~3 KB | ~4 KB |
|
||||
| `@pulse-libs/core/types` | ~1 KB | ~1 KB |
|
||||
| `@pulse-libs/core/validators` | ~3 KB | ~3 KB |
|
||||
| `@pulse-libs/core/components` | ~7 KB | ~9 KB |
|
||||
|
||||
## DTS — flat(2) vs flat(Infinity)
|
||||
|
||||
`flat(Infinity)` quebra o TypeScript Declaration Generator do tsup em pacotes complexos.
|
||||
`flat(2)` é o máximo necessário (nossas arrays no máximo 2 níveis de aninhamento: [cls, [cls2]]).
|
||||
@@ -0,0 +1,57 @@
|
||||
# Docker Build Guide — @pulse-libs/core
|
||||
|
||||
## Multi-stage Build
|
||||
|
||||
```
|
||||
Stage 1: build → instala deps + compila tsup
|
||||
Stage 2: prod-deps → npm install --prod apenas
|
||||
Stage 3: final → dist/ + node_modules (mínimo)
|
||||
```
|
||||
|
||||
## Build Local
|
||||
|
||||
```bash
|
||||
docker build -t pulse-libs/core:1.0.0-beta.1 .
|
||||
```
|
||||
|
||||
## Tamanho esperado
|
||||
|
||||
| Image | Aprox. |
|
||||
|-------|--------|
|
||||
| node:20-alpine base | ~170 MB |
|
||||
| Com build completo | ~300 MB |
|
||||
| Final (prod only) | **~120 MB** |
|
||||
|
||||
## TAGS Recomendadas
|
||||
|
||||
```bash
|
||||
# Latest
|
||||
docker tag pulse-libs/core:1.0.0-beta.1 pulse-libs/core:latest
|
||||
|
||||
# Por versão
|
||||
docker tag pulse-libs/core:1.0.0-beta.1 pulse-libs/core:1.0.0-beta
|
||||
docker tag pulse-libs/core:1.0.0-beta.1 pulse-libs/core:1.0
|
||||
|
||||
# Por commit SHA
|
||||
docker tag pulse-libs/core:1.0.0-beta.1 pulse-libs/core:sha-$(git rev-parse --short HEAD)
|
||||
```
|
||||
|
||||
## Push para registry
|
||||
|
||||
```bash
|
||||
docker push registry.example.com/pulse/core:1.0.0-beta.1
|
||||
```
|
||||
|
||||
## .dockerignore
|
||||
|
||||
```
|
||||
node_modules/
|
||||
dist/
|
||||
coverage/
|
||||
.env
|
||||
.env.*
|
||||
.git/
|
||||
.github/
|
||||
*.log
|
||||
.DS_Store
|
||||
```
|
||||
Reference in New Issue
Block a user