# Piano di migrazione GitHub — `persona-chat-sdk`

> Migrazione da Bitbucket (`applicaguru/persona-chat-sdk`) a GitHub
> (`applica-software-guru/persona-chat-sdk`, privato). Stesso schema dei
> repo precedenti (report-generator, persona-mcp-google-documentai), con una
> differenza chiave: il deploy è la **pubblicazione su npm**, e avviene tramite
> **trusted publishing OIDC** — nessun token da gestire.

## Contesto: perché nessun NPM_TOKEN

- I **classic token** npm (quello usato dalla vecchia pipeline Bitbucket) sono
  stati **revocati permanentemente da npm il 9 dicembre 2025**: il publish da
  Bitbucket era di fatto già rotto.
- I **granular token** hanno scadenza obbligatoria (write max 90 giorni).
- Soluzione: **trusted publishing** (standard OpenSSF, GA su npm da luglio
  2025) — GitHub Actions firma ogni publish con token OIDC effimero. Zero
  segreti nel repo, zero rotazioni. Config su npmjs.com: package → Settings →
  Trusted Publisher → GitHub Actions (`applica-software-guru/persona-chat-sdk`,
  workflow `deploy.yml`, azione consentita "npm publish").

## Fasi

| Fase | Cosa | Stato |
|---|---|---|
| A | **Repo locale**: lint verde (convenzione `_` per unused, playground escluso, helper `isPersonaDebug()`), script `test: vitest run`, commit a nome RoBYCoNTe | ✅ 2026-09-24 |
| B | **GitHub**: repo privato, push `main` + branch attivi + 86 tag (`0.1.1`–`0.1.124` + 24 legacy `1.0.*`) | ✅ 2026-09-24 |
| C | **Workflows**: `ci.yml` (PR: lint/test/build) + `deploy.yml` (push main: versione riconciliata sui tag `0.1.*` → build → publish npm OIDC → tag git). Prima versione: **`0.1.125`** | ✅ 2026-09-24 |
| D | **Cutover**: rimosso `bitbucket-pipelines.yml`, README con badge Actions + campo `repository` nel package.json; resta disable pipeline + archiviazione Bitbucket | ✅ 2026-09-24 |

## Decisioni

- **Versioning**: riconciliazione sui tag git `0.1.*` (max + 1) — la serie
  attiva è `0.1.x`; i tag legacy `1.0.*` (era preistorica) non partecipano al
  calcolo. Il `package.json` nel repo resta a `0.0.0` (come da pipeline
  Bitbucket: la versione viene applicata solo nel workspace CI).
- **Publish**: `npm publish --access public` con OIDC; `npm >= 11.5.1`
  garantito nel workflow (`npm i -g npm@^11`, Node 22 non bundla npm 11).
- **CI su PR only**: il push su `main` è già coperto integralmente da
  `deploy.yml` (lint + test + build come gate del publish) — niente run doppi.
- **Zero segreti GitHub**: diversamente dagli altri repo, qui non serve
  alcun secret (nessun GCR, nessun deploy-hook, publish via OIDC).

## Verifica primo deploy (Fase C)

1. Run verde: versione `0.1.125`, publish ok, tag `0.1.125` creato
2. `npm view @applica-software-guru/persona-chat-sdk version` → `0.1.125`
3. Pagina npm con link al repository GitHub