@pawareapp/twitch-ext-toolkit

Tipo: pacchetto npm pubblicabile (CLI + libreria) per il build, test locale e packaging di estensioni Twitch.

Stato: spec di sviluppo — repo vuota, da implementare.

Namespace npm: @pawareapp/twitch-ext-toolkit

0. Scopo & contesto

Questo pacchetto estrae e generalizza gli script di tooling già collaudati in produzione nell'estensione Twitch rafflyx, rendendoli plug-and-play per qualsiasi estensione Twitch (a partire da RIVYLO).

Obiettivo: un'unica CLI (twitch-ext) che copra il ciclo di vita locale dell'estensione:

• dev/serve: HTTPS locale + tunnel per test su mobile + istruzioni per la Twitch Console.
• build: build Vite multi-page dell'estensione per ambiente.
• package: verifica file richiesti + manifest + ZIP pronto per la Twitch Console.

🟢 Questo è il PRIMO progetto da realizzare (prima di RIVYLO). Lo sviluppo del toolkit include anche la sua integrazione nelle due repo consumer (vedi §0.1): è parte del Definition of Done.

0.1 Definition of Done — il toolkit va anche INTEGRATO

Lo sviluppo non termina con la pubblicazione del pacchetto: devi anche integrarlo nelle due estensioni esistenti/in-arrivo, sostituendo gli script locali con la CLI:

1. Realizzare e pubblicare @pawareapp/twitch-ext-toolkit (vedi roadmap §7).
2. Integrare in rafflyx (/Users/davide/git/rafflyx):
   • aggiungere il pacchetto come devDependency;
   • creare twitch-ext.config.*, twitch-manifest.json (estraendo i valori dal package-twitch.js attuale: name "RAFFLYX", panel_height 300, support email, ecc.);
   • rimpiazzare gli script scripts/serve-extension.js, scripts/extension-express-server.js, scripts/build-extension.sh, scripts/package-twitch.js con i comandi twitch-ext negli scripts di package.json (dev:extension, extension:build:*);
   • verificare che dev:extension, build staging/production e packaging funzionino identici a prima;
   • non toccare init-database.sh né seed-themes.ts (restano specifici).
3. Integrare in rivylo (/Users/davide/git/rivylo):
   • stesso lavoro (devDependency + twitch-ext.config.* + twitch-manifest.json + scripts), così RIVYLO parte già pulito senza copiare script in scripts/.
   • Il README di RIVYLO (§28.2) dà per scontato che questo pacchetto esista già.

Esito atteso: entrambe le repo consumano lo stesso tooling; nessuno script di estensione duplicato/hardcoded.

Repository correlate (riferimento locale)

• Fonti da cui estrarre il codice (blueprint): /Users/davide/git/rafflyx/scripts/
  • serve-extension.js (orchestratore dev, 349 righe)
  • extension-express-server.js (server HTTPS statico, 108 righe)
  • build-extension.sh (wrapper build, 53 righe)
  • package-twitch.js (packaging ZIP, 134 righe)
• Primo consumer: /Users/davide/git/rivylo (vedi suo README.md, §28 e §20–§30). RIVYLO consuma questo pacchetto come devDependency, non copia gli script.
• Da NON sviluppare qui: logica di prodotto, backend, infra Docker/Swarm, CI Woodpecker, init-database.sh, seed-themes.ts (restano nei progetti consumer).

⚠️ Gli script rafflyx contengono branding hardcoded ("RAFFLYX"), path fissi (vite.config.extension.ts, .cert/, dist-extension/) e un manifest.json inline. Il compito del toolkit è rimuovere questi hardcoded rendendoli configurabili (vedi §3 Config).

1. Stack & requisiti

• Runtime: Node.js ≥ 24 (ESM, "type": "module"), coerente con rafflyx/rivylo.
• Linguaggio: TypeScript (build verso ESM + type declarations). Output CLI eseguibile.
• Dipendenze runtime previste: express (server statico), commander o yargs (parsing CLI), picocolors/chalk (output). Mantenere il set minimo.
• Prerequisiti di sistema (documentare, non installare): mkcert, cloudflared, zip. Sono gli stessi tool elencati nei pacchetti nix di rafflyx (.replit).
• Peer/assunzioni: il progetto consumer usa Vite per buildare l'estensione (config separata stile vite.config.extension.ts).

2. Comandi CLI (contratto)

Binario: twitch-ext (campo bin in package.json). Tutti i comandi leggono la config di progetto (§3) e accettano override via flag.

twitch-ext serve

Orchestratore per il test locale (da serve-extension.js + extension-express-server.js). Flusso:

1. Verifica che cloudflared sia installato (istruzioni se assente).
2. Verifica/genera i certificati in certDir: cerca localhost.pem + localhost-key.pem; se mancano, verifica mkcert (con istruzioni install per macOS/Win/Linux) e genera con mkcert -cert-file ... -key-file ... localhost 127.0.0.1 ::1.
3. Esegue la build estensione in modalità locale (comando configurabile, default deriva da buildCommand).
4. Avvia un server HTTPS (Express) su port (default 8080) servendo distDir, con header ngrok-skip-browser-warning: true e route esplicite /component, /mobile, /config → relativi .html (più express.static).
5. Crea un tunnel Cloudflare (cloudflared tunnel --url https://localhost:<port>), estrae l'URL *.trycloudflare.com.
6. Stampa istruzioni per configurare la Twitch Developer Console (Asset Hosting Root URL + path component/mobile/config).
7. Graceful shutdown (SIGINT/SIGTERM) di server + tunnel.

Flag: --port, --cert-dir, --dist, --build-command, --no-tunnel (solo HTTPS locale), --no-build (servi un dist già pronto).

twitch-ext build [--mode <env>]

Da build-extension.sh. Esegue la build Vite multi-page dell'estensione per l'ambiente indicato.

• --mode ∈ local | staging | production (default production). Mappa su vite build --mode extension.<env> --config <viteConfig>.
• Legge viteConfig e gli .env.extension.<env> dal progetto consumer.

twitch-ext package

Da package-twitch.js. Crea lo ZIP per la Twitch Console.

1. Verifica esistenza distDir.
2. Copia ricorsiva di distDir in una cartella di staging (outputDir/package-content).
3. Verifica file richiesti (default component.html, mobile.html, config.html; lista configurabile via requiredFiles).
4. Scrive manifest.json letto da file di progetto (manifestPath) — NON inline/hardcoded.
5. Crea lo ZIP (zipName) con zip -r nativo; stampa size e next-steps per la Console.

Flag: --dist, --out, --manifest, --zip-name, --required <a,b,c>.

twitch-ext dev (alias opzionale)

Alias di serve con --mode local, per allineamento agli script npm tipo dev:extension.

3. Config di progetto

Il consumer definisce un file twitch-ext.config.{js,json,ts} nella root. Schema (con default):

{
  "viteConfig": "vite.config.extension.ts", // config Vite dell'estensione
  "distDir": "dist-extension",              // output build
  "outputDir": "twitch-package",            // staging + zip
  "certDir": ".cert",                       // certificati mkcert (localhost.pem / localhost-key.pem)
  "port": 8080,                             // server HTTPS locale
  "buildCommand": null,                     // override completo del comando build (altrimenti derivato da viteConfig+mode)
  "manifestPath": "twitch-manifest.json",   // manifest letto da file (NO inline)
  "zipName": "extension.zip",
  "requiredFiles": ["component.html", "mobile.html", "config.html"],
  "tunnel": "cloudflare"                    // cloudflare | none
}

Tutti i campi sono sovrascrivibili via flag CLI. La risoluzione: flag > config file > default.

4. Cosa generalizzare rispetto a rafflyx (checklist estrazione)

• [ ] Rimuovere ogni stringa hardcoded "RAFFLYX"/branding dai log.
• [ ] Parametrizzare i path: vite.config.extension.ts, .cert/, dist-extension/, twitch-package/, zipName.
• [ ] package: leggere manifest.json da manifestPath invece di generarlo inline (rimuovere il template name/description/panel_height/...).
• [ ] requiredFiles configurabile (rafflyx assume sempre component/mobile/config).
• [ ] Mantenere: header ngrok-skip-browser-warning, route /component|/mobile|/config, graceful shutdown, verifica/generazione mkcert, parsing URL trycloudflare.com, istruzioni Twitch Console.
• [ ] CLI unica twitch-ext con sottocomandi serve|build|package|dev.

5. Integrazione lato consumer (RIVYLO)

Nel package.json del consumer:

{
  "devDependencies": { "@pawareapp/twitch-ext-toolkit": "^0.1.0" },
  "scripts": {
    "dev:extension": "twitch-ext serve",
    "extension:build:staging": "twitch-ext build --mode staging",
    "extension:build:production": "twitch-ext build --mode production",
    "extension:package": "twitch-ext package"
  }
}

Il consumer fornisce: twitch-ext.config.*, vite.config.extension.ts, .env.extension.*, twitch-manifest.json, e (per serve) i prerequisiti mkcert/cloudflared/zip.

6. Struttura repo proposta

@pawareapp/twitch-ext-toolkit/
├─ package.json            # bin: { "twitch-ext": "dist/cli.js" }, type: module
├─ tsconfig.json
├─ src/
│  ├─ cli.ts               # entry CLI (commander/yargs) → sottocomandi
│  ├─ config.ts            # load/merge config (flag > file > default) + validazione
│  ├─ commands/
│  │  ├─ serve.ts          # orchestratore (da serve-extension.js)
│  │  ├─ build.ts          # build Vite (da build-extension.sh)
│  │  └─ package.ts        # zip + manifest (da package-twitch.js)
│  ├─ lib/
│  │  ├─ https-server.ts   # server statico HTTPS (da extension-express-server.js)
│  │  ├─ mkcert.ts         # verifica/genera certificati
│  │  ├─ tunnel.ts         # cloudflared
│  │  └─ console-hints.ts  # istruzioni Twitch Console
│  └─ index.ts             # export libreria (uso programmatico opzionale)
├─ README.md               # questo file
└─ LICENSE

7. Roadmap di sviluppo (toolkit)

1. T0 — Scaffold: package.json (bin, ESM, TS), tsconfig, CLI vuota con sottocomandi.
2. T1 — lib/https-server: porting di extension-express-server.js (generalizzato).
3. T2 — serve: porting di serve-extension.js (mkcert + build + tunnel + hints), config-driven.
4. T3 — build: porting di build-extension.sh.
5. T4 — package: porting di package-twitch.js con manifest da file.
6. T5 — Config & docs: loader twitch-ext.config.*, validazione, esempi, README finale.
7. T6 — Pubblicazione: npm publish --access public sotto @pawareapp (oppure consumo via path/workspace finché non pubblicato).
8. T7 — Integrazione rafflyx: devDependency + config + manifest + sostituzione script; verifica parità funzionale (vedi §0.1).
9. T8 — Integrazione rivylo: devDependency + config + manifest + scripts (vedi §0.1).

T7 e T8 fanno parte del Definition of Done di questo progetto (§0.1): il toolkit si considera completo solo quando entrambe le repo lo consumano.

8. Note

• I prerequisiti di sistema (mkcert, cloudflared, zip) NON vanno installati dal pacchetto: vanno verificati con messaggi d'errore chiari e istruzioni per OS.
• Mantenere il pacchetto focalizzato sul tooling estensione: niente logica di backend, DB, deploy o dominio.
• Compatibilità Vite: rafflyx usa Vite 8 (Rolldown) con un plugin custom hoistExtensionHtml; quel plugin resta nel vite.config.extension.ts del consumer, non nel toolkit.