@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):
   • 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.