it4-tools (bootstrap público)

Bootstrap de auth da IT4 Solution. Roda uma vez numa máquina nova pra configurar o ~/.npmrc apontando pro feed Azure Artifacts privado e (por default) instalar globalmente @it4solution/tools.

Não confundir com @it4solution/tools — este package (it4-tools, unscoped, no npmjs.com público) só faz bootstrap. A CLI real é o @it4solution/tools (privado, feed Azure), que esse bootstrap instala no final.

Uso

npx -y it4-tools

Fluxo:

1. Device code flow — abre uma URL + código no navegador pra você logar com sua conta IT4 (Azure AD).
2. Cria um PAT (Personal Access Token) no Azure DevOps com scope vso.packaging (read), válido por 90 dias, com displayName="it4-tools (<hostname>)".
3. Escreve ~/.npmrc com o token. Migra config IT4 antiga (substitui linhas do feed IT4 com token vencido/compartilhado), preserva tudo que não é IT4.
4. npm i -g @it4solution/tools — instala o core do CLI (bin it4).

O CLI é core + plugins por capacidade: o core traz só auth/config. Instale os plugins que for usar (o mesmo ~/.npmrc configurado acima autentica o download deles):

it4 plugins install @it4solution/plugin-create          # cria projetos
it4 plugins install @it4solution/plugin-skills          # skills do Claude Code
it4 plugins install @it4solution/plugin-publish-nuget   # publica libs .NET
it4 plugins                                             # lista o que está instalado

Depois disso, it4 --help mostra os comandos disponíveis. Pra re-logar quando o PAT expirar (em ~90 dias), rode de novo npx -y it4-tools ou it4 auth login (mesmo caminho).

Flags

| Flag | Default | Descrição | | ----------------------- | --------------- | --------------------------------------------------------------------------------------------------- | | --no-install | — | Configura .npmrc mas não instala o CLI globalmente. | | --cli-version <v> | latest | Versão específica do @it4solution/tools a instalar. | | --pat-validity <dias> | 90 | Validade do PAT em dias (máx 365). | | --scope <s> | vso.packaging | Scope do PAT (vso.packaging = read; vso.packaging_write = read+write, necessário pra publicar). | | --dry-run | — | Autentica e mostra o .npmrc que seria escrito, sem salvar. | | --help, -h | — | Mostra essa ajuda. |

Troubleshooting

• Browser não abre / sem internet no terminal: copie a URL e o código manualmente pra outra máquina/celular e cole lá. O device flow tolera ambientes headless por design.
• AADSTS... no login: sua conta provavelmente não tem permissão no tenant da IT4. Fale com o time de TI/identidade.
• PAT criado mas npm install ainda dá 401: confira npm config get userconfig — deve apontar pro mesmo ~/.npmrc que o bootstrap escreveu. Em alguns setups (corp Windows com npmrc em AppData\Roaming), pode haver divergência.

Mais detalhes

Spec canônica: ver docs/specs/04-auth-bootstrap.md no repo @it4solution/tools.