it4-tools 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# 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
+
+```bash
+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 CLI real.
+
+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`.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "it4-tools",
+  "version": "0.1.0",
+  "description": "Bootstrap público: autentica no Azure Artifacts da IT4 e instala @it4solution/tools.",
+  "license": "ISC",
+  "author": "Diego Andrade",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "it4-tools": "src/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://it4solution@dev.azure.com/it4solution/IT4360/_git/IT4.Tools"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@azure/identity": "^4.4.1",
+    "@clack/prompts": "^1.4.0",
+    "picocolors": "^1.1.1"
+  }
+}

package/src/auth.js

@@ -0,0 +1,68 @@
+import os from "node:os";
+import { DeviceCodeCredential } from "@azure/identity";
+
+// Public clientId da Azure CLI — reusado por inúmeras ferramentas de dev.
+// V2: registrar app dedicado "IT4 Tools" no Entra ID e trocar aqui (ver
+// docs/specs/04-auth-bootstrap.md, tabela "Defaults documentados").
+const AZURE_CLI_CLIENT_ID = "04b07795-8ddb-461a-bbee-02f9e1bf7b46";
+
+// Resource ID do Azure DevOps (constante global da Microsoft).
+const AZURE_DEVOPS_RESOURCE = "499b84ac-1321-427f-aa17-267ca6975798/.default";
+
+const IT4_ORG = "it4solution";
+const PAT_ENDPOINT = `https://vssps.dev.azure.com/${IT4_ORG}/_apis/tokens/pats?api-version=7.1-preview.1`;
+
+export async function getBearerToken({ onPrompt }) {
+  const credential = new DeviceCodeCredential({
+    tenantId: "organizations",
+    clientId: AZURE_CLI_CLIENT_ID,
+    userPromptCallback: ({ verificationUri, userCode }) => {
+      onPrompt({ verificationUri, userCode });
+    },
+  });
+  const token = await credential.getToken(AZURE_DEVOPS_RESOURCE);
+  if (!token?.token) {
+    throw new Error("Azure AD não retornou um token.");
+  }
+  return token.token;
+}
+
+export async function exchangeForPat({ bearerToken, validityDays, scope }) {
+  const validTo = new Date(Date.now() + validityDays * 24 * 60 * 60 * 1000).toISOString();
+  const displayName = `it4-tools (${os.hostname()})`;
+
+  const res = await fetch(PAT_ENDPOINT, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${bearerToken}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+    body: JSON.stringify({
+      displayName,
+      scope,
+      validTo,
+      allOrgs: false,
+    }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`Falha ao criar PAT (HTTP ${res.status} ${res.statusText}): ${body}`);
+  }
+
+  const data = await res.json();
+  if (data.patTokenError && data.patTokenError !== "none") {
+    throw new Error(`Azure DevOps recusou criar PAT: ${data.patTokenError}`);
+  }
+  if (!data.patToken?.token) {
+    throw new Error("Resposta do Azure DevOps não trouxe o PAT.");
+  }
+
+  return {
+    pat: data.patToken.token,
+    displayName: data.patToken.displayName,
+    validTo: data.patToken.validTo,
+    scope: data.patToken.scope,
+  };
+}

package/src/index.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { cancel, confirm, intro, isCancel, log, outro, spinner } from "@clack/prompts";
+import pc from "picocolors";
+import { exchangeForPat, getBearerToken } from "./auth.js";
+import { buildNpmrc, NPMRC_PATH, readNpmrc, summarizeChanges, writeNpmrc } from "./npmrc.js";
+
+const DEFAULTS = {
+  install: true,
+  cliVersion: "latest",
+  patValidityDays: 90,
+  scope: "vso.packaging",
+  dryRun: false,
+};
+
+function printHelp() {
+  process.stdout.write(`it4-tools — bootstrap de auth da IT4 Solution
+
+Uso:
+  npx -y it4-tools [opções]
+
+Opções:
+  --no-install                Configura .npmrc mas não instala @it4solution/tools.
+  --cli-version <v>           Versão do CLI a instalar (default: latest).
+  --pat-validity <dias>       Validade do PAT em dias (default: 90, máx 365).
+  --scope <s>                 Scope do PAT: vso.packaging | vso.packaging_write
+                              (default: vso.packaging).
+  --dry-run                   Mostra o .npmrc resultante sem escrever.
+  -h, --help                  Mostra essa ajuda.
+
+Detalhes: README.md ou docs/specs/04-auth-bootstrap.md
+`);
+}
+
+function parseArgs(argv) {
+  const args = { ...DEFAULTS };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--no-install":
+        args.install = false;
+        break;
+      case "--dry-run":
+        args.dryRun = true;
+        break;
+      case "-h":
+      case "--help":
+        printHelp();
+        process.exit(0);
+        break;
+      case "--cli-version":
+        args.cliVersion = argv[++i];
+        break;
+      case "--pat-validity": {
+        const n = Number.parseInt(argv[++i], 10);
+        if (!Number.isFinite(n) || n < 1 || n > 365) {
+          console.error(`Flag --pat-validity inválida: precisa ser 1..365.`);
+          process.exit(1);
+        }
+        args.patValidityDays = n;
+        break;
+      }
+      case "--scope": {
+        const v = argv[++i];
+        if (v !== "vso.packaging" && v !== "vso.packaging_write") {
+          console.error(`Flag --scope inválida: use "vso.packaging" ou "vso.packaging_write".`);
+          process.exit(1);
+        }
+        args.scope = v;
+        break;
+      }
+      default:
+        console.error(`Flag desconhecida: ${a}`);
+        printHelp();
+        process.exit(1);
+    }
+  }
+  return args;
+}
+
+function bail(message) {
+  cancel(message);
+  process.exit(0);
+}
+
+function unwrap(value, cancelMessage = "Cancelado.") {
+  if (isCancel(value)) bail(cancelMessage);
+  return value;
+}
+
+function runNpmInstallGlobalCli(version) {
+  const pkg =
+    version && version !== "latest" ? `@it4solution/tools@${version}` : "@it4solution/tools";
+  const args = ["install", "--global", pkg];
+  return new Promise((resolve, reject) => {
+    const child =
+      process.platform === "win32"
+        ? spawn(`npm ${args.join(" ")}`, { shell: true, stdio: "inherit" })
+        : spawn("npm", args, { stdio: "inherit" });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`npm install falhou (exit ${code}).`));
+    });
+  });
+}
+
+async function main() {
+  const opts = parseArgs(process.argv);
+
+  intro(pc.bgBlue(pc.white(" IT4 Tools — setup ")));
+
+  log.step("Autenticação Azure AD (device code flow)");
+  let bearer;
+  try {
+    bearer = await getBearerToken({
+      onPrompt: ({ verificationUri, userCode }) => {
+        log.info(`Abra ${pc.cyan(verificationUri)} no navegador.`);
+        log.info(`Cole o código: ${pc.bold(pc.yellow(userCode))}`);
+        log.info("Aguardando login...");
+      },
+    });
+  } catch (err) {
+    log.error(`Falha no login Azure AD: ${err.message}`);
+    process.exit(1);
+  }
+  log.success("Autenticado.");
+
+  const patSpinner = spinner();
+  patSpinner.start("Criando PAT no Azure DevOps...");
+  let pat;
+  try {
+    pat = await exchangeForPat({
+      bearerToken: bearer,
+      validityDays: opts.patValidityDays,
+      scope: opts.scope,
+    });
+  } catch (err) {
+    patSpinner.stop("Falha ao criar PAT.", 1);
+    log.error(err.message);
+    process.exit(1);
+  }
+  const validToShort = pat.validTo.slice(0, 10);
+  patSpinner.stop(`PAT criado (${pat.displayName}), válido até ${validToShort}.`);
+
+  const existing = await readNpmrc();
+  const newContent = buildNpmrc(existing, pat.pat);
+  const summary = summarizeChanges(existing, pat.pat);
+
+  if (opts.dryRun) {
+    log.info(`Dry-run — não vou escrever ${NPMRC_PATH}.`);
+    log.info(`Conteúdo que seria escrito:\n\n${newContent}`);
+    if (summary.replaced) {
+      log.warn(`Linhas IT4 antigas que seriam removidas: ${summary.removedLines.length}.`);
+    }
+    outro(pc.dim("Dry-run completo."));
+    return;
+  }
+
+  await writeNpmrc(newContent);
+  if (summary.replaced) {
+    log.success(
+      `~/.npmrc atualizado (${summary.removedLines.length} linha(s) IT4 antiga(s) substituída(s)).`,
+    );
+  } else {
+    log.success(`~/.npmrc configurado.`);
+  }
+
+  if (!opts.install) {
+    outro(`Pronto. Rode ${pc.cyan("npm i -g @it4solution/tools")} quando quiser instalar o CLI.`);
+    return;
+  }
+
+  const shouldInstall = unwrap(
+    await confirm({
+      message: "Instalar @it4solution/tools globalmente agora?",
+      initialValue: true,
+    }),
+  );
+
+  if (!shouldInstall) {
+    outro(
+      `Beleza. Quando quiser instalar: ${pc.cyan("npm i -g @it4solution/tools")}. Depois use ${pc.cyan("it4 --help")}.`,
+    );
+    return;
+  }
+
+  const installSpinner = spinner();
+  installSpinner.start(
+    `Instalando @it4solution/tools${opts.cliVersion !== "latest" ? `@${opts.cliVersion}` : ""}...`,
+  );
+  try {
+    await runNpmInstallGlobalCli(opts.cliVersion);
+    installSpinner.stop("@it4solution/tools instalado.");
+  } catch (err) {
+    installSpinner.stop("npm install falhou.", 1);
+    log.error(err.message);
+    log.info(
+      `Você ainda pode tentar manualmente: ${pc.cyan("npm i -g @it4solution/tools")}. O ~/.npmrc já foi configurado.`,
+    );
+    process.exit(1);
+  }
+
+  outro(`Pronto. Use ${pc.cyan("it4 --help")} pra ver os comandos disponíveis.`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/npmrc.js

@@ -0,0 +1,61 @@
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+export const NPMRC_PATH = path.join(os.homedir(), ".npmrc");
+
+const IT4_FEED_URL =
+  "it4solution.pkgs.visualstudio.com/IT4360/_packaging/IT4-packages/npm/registry/";
+const IT4_HOST_PATTERN =
+  /^\/\/[^/]*(?:it4solution\.pkgs\.visualstudio\.com|pkgs\.dev\.azure\.com\/it4solution)/i;
+const IT4_SCOPE_REGISTRY = /^@it4solution:registry\s*=/i;
+const DEFAULT_REGISTRY = /^registry\s*=\s*https?:\/\/registry\.npmjs\.org/im;
+
+export async function readNpmrc() {
+  try {
+    return await fs.readFile(NPMRC_PATH, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return "";
+    throw err;
+  }
+}
+
+export async function writeNpmrc(content) {
+  await fs.writeFile(NPMRC_PATH, content, "utf8");
+}
+
+function isIt4Line(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith(";")) return false;
+  if (IT4_SCOPE_REGISTRY.test(trimmed)) return true;
+  if (IT4_HOST_PATTERN.test(trimmed)) return true;
+  return false;
+}
+
+export function buildNpmrc(existingContent, pat) {
+  const lines = (existingContent ?? "").split(/\r?\n/);
+  const kept = lines.filter((line) => !isIt4Line(line));
+  while (kept.length > 0 && kept[kept.length - 1].trim() === "") kept.pop();
+
+  const it4Block = [
+    `@it4solution:registry=https://${IT4_FEED_URL}`,
+    `//${IT4_FEED_URL}:_authToken=${pat}`,
+  ];
+
+  const result = [...kept, ...it4Block];
+  if (!DEFAULT_REGISTRY.test(existingContent)) {
+    result.push("registry=https://registry.npmjs.org/");
+  }
+  return result.join("\n") + "\n";
+}
+
+export function summarizeChanges(existingContent, pat) {
+  const before = (existingContent ?? "").split(/\r?\n/).filter((l) => isIt4Line(l));
+  const replaced = before.length > 0;
+  return {
+    replaced,
+    removedLines: before,
+    feedUrl: `https://${IT4_FEED_URL}`,
+    patPreview: pat ? `${pat.slice(0, 4)}...${pat.slice(-4)}` : "",
+  };
+}