# @uappi/public-sdk

Pacotes públicos (composables, tipos e componentes Vue 3) para desenvolvimento do ecossistema Uappi. Publicado como `.ts`/`.vue` cru — sem etapa de build — então os erros de compilação (imports de tipo, `verbatimModuleSyntax`, etc.) só aparecem quando o projeto consumidor faz o type-check. Por isso este repositório valida tudo antes de deixar chegar lá.

## Setup

```
npm install
```

Isso também instala os git hooks do Husky via `prepare`.

## Scripts

| Script | O que faz |
|---|---|
| `npm run lint` | ESLint (`eslint.config.mjs`), com a regra `@typescript-eslint/consistent-type-imports` — pega imports de tipo sem `type`, que é a causa mais comum de quebrar o build de projetos consumidores com `verbatimModuleSyntax` habilitado. |
| `npm run type-check` | `tsc --noEmit` usando `tsconfig.json`, que tem `verbatimModuleSyntax: true` propositalmente — reproduz localmente o mesmo erro que apareceria no projeto consumidor. |
| `npm run prepush` | `lint` + `type-check` juntos. Roda automaticamente antes de qualquer `git push` (hook `.husky/pre-push`). |

Se `npm run prepush` falhar, o `git push` é bloqueado. Corrija os erros reportados antes de tentar de novo.

## Fluxo de desenvolvimento

1. Crie uma branch a partir da `main`.
2. Faça as alterações. Rode `npm run lint` e `npm run type-check` localmente se quiser adiantar (o pre-push já roda isso antes do push).
3. Commite usando **Conventional Commits** — o prefixo do commit decide o bump de versão automático quando a MR for mergeada (veja [Versionamento e publicação](#versionamento-e-publicação)):
   - `fix: ...` → patch
   - `feat: ...` → minor
   - `feat!: ...` ou corpo do commit com `BREAKING CHANGE: ...` → major
   - qualquer outro prefixo (`chore:`, `docs:`, `refactor:`, etc.) → patch por padrão
4. Abra o Merge Request para a `main`. A pipeline roda o job `verify` (lint + type-check) automaticamente na MR.
5. Após aprovado, faça o merge. Isso dispara o job `release` na `main` — não é preciso bumpar versão nem publicar manualmente.

## Versionamento e publicação (CI/CD)

O `.gitlab-ci.yml` tem dois jobs:

- **`verify`** — roda em toda pipeline de Merge Request. Executa `lint` e `type-check`. É a mesma checagem do hook local, mas visível na revisão do MR.
- **`release`** — roda apenas em push direto na `main` (ou seja, no merge de uma MR aprovada). Faz, nessa ordem:
  1. Roda `lint` e `type-check` de novo (segurança extra, já que o hook local pode ser pulado com `--no-verify`).
  2. Olha os commits desde a última tag `vX.Y.Z` e decide o bump (patch/minor/major) pelas regras de Conventional Commits acima.
  3. Atualiza a versão no `package.json`.
  4. Publica no npm (`npm publish --access public`).
  5. Só se a publicação funcionar: commita a nova versão e cria a tag `vX.Y.Z` de volta na `main`, com `[skip ci]` no commit para não disparar a pipeline de novo.

Se o job `release` falhar (ex: token expirado, lint quebrado), nada é publicado e a versão não muda — corrija o problema e re-rode o job manualmente pela pipeline no GitLab, sem precisar de outra MR.

### Variáveis de CI/CD necessárias (Settings → CI/CD → Variables no GitLab)

| Variável | Uso | Observação |
|---|---|---|
| `NPM_TOKEN` | Autenticação no registry do npm para o `npm publish` | Token do tipo **Granular Access Token**, escopo `@uappi` ou pacote específico, permissão *Read and write*, com expiração — precisa ser rotacionado periodicamente. |
| `GITLAB_PUSH_TOKEN` | Permite o job `release` dar `git push`/criar tag de volta na `main` protegida | Personal ou Project Access Token, scope `write_repository`, com role que tenha permissão de push na `main` (Maintainer, se a proteção da branch exigir). Também expira — se o `release` começar a falhar com 401, é o primeiro lugar a checar. |

Ambas marcadas como **Protected** e **Masked**.

### Bootstrap (já feito, só como referência)

O job `release` precisa de uma tag de referência para calcular "commits desde o último release". A tag inicial foi criada manualmente uma única vez, apontando para a versão já publicada no npm no momento em que o CI foi introduzido:

```
git tag v1.2.9 origin/main
git push origin v1.2.9
```

Não repita esse passo — é só histórico de como o processo começou.