opencode-wyvern 0.1.1 → 0.2.1

package/README.md

@@ -15,12 +15,18 @@ oc-setup
 
 La procedura guidata:
 
-1. **Moduli** — scegli quali sezioni attivare (default: tutte).
-2. **Connessione** — solo i dati necessari ai moduli scelti
+1. **Scenario** — scegli subito il contesto: **Client + Server** (tutto),
+   **Solo client**, **Solo server** o **Personalizzato** (sezioni singole).
+2. Con **Solo server** viene chiesto come applicare lo script: **via SSH da questo
+   client** o **in locale su questa macchina (localhost)** — in quest'ultimo caso
+   non serve host/porta né la chiave SSH.
+3. **Moduli** — con uno scenario preimpostato le sezioni sono già selezionate;
+   con "Personalizzato" le scegli una a una.
+4. **Connessione** — solo i dati necessari ai moduli scelti
    (host obbligatorio solo se usi SSH/sezioni remote; coi soli client basta l'alias).
-3. **Provider / plugin / claude-mem** — solo se le sezioni corrispondenti sono attive;
-   endpoint e chiavi sono richieste al volo.
-4. **Applicazione** — chiave SSH, alias, profili client e bootstrap remoto.
+5. **Provider / plugin / claude-mem / comandi / MCP** — solo se le sezioni
+   corrispondenti sono attive; endpoint e chiavi vengono richieste al volo.
+6. **Applicazione** — chiave SSH, alias, profili client e bootstrap (remoto o locale).
 
 Le sezioni restano salvate in `~/.config/opencode-wyvern/config.json`
 (solo dati non sensibili) e puoi attivarle/disattivarle in seguito.
@@ -36,6 +42,17 @@ oc-setup deactivate <sezione>         disattiva un modulo
 oc-setup print <sezione>              stampa l'artefatto di una sezione
 ```
 
+Nella procedura guidata: frecce/Spazio per navigare, `Invio` conferma,
+`Esc`/`Ctrl+C` annullano, `q` esce. **CTRL+SHIFT+C** in un terminale vero copia
+la selezione (gestito dal terminale, mai visto dal wizard) e **CTRL+SHIFT+V**
+incolla: un token con la lettera `q` o con un `a-capo` finale viene accettato
+senza chiudere il setup e senza caratteri spuri.
+
+La **cartella remota di default** (del menu Connessione) parte già dalla home
+dell'utente sul server: lasciala **vuota** per `~`, scrivi un percorso relativo
+(es. `projects/foo` → `~/projects/foo`) o assoluto (`/srv/data`). Non viene mai
+accodata al valore precedente.
+
 ## Moduli
 
 | Sezione       | Dove  | Cosa fa |
@@ -44,7 +61,8 @@ oc-setup print <sezione>              stampa l'artefatto di una sezione
 | `client-pwsh` | locale | comandi `oc-*` nel profilo PowerShell (`oc-sessions`, `oc-go`, `oc-resume`, `oc-recap`, ...) |
 | `client-bash` | locale | stesso blocco in `~/.bashrc` |
 | `server`      | remoto | controlla node/npm, installa opencode se manca, crea `~/.config/opencode` + `AGENTS.md` |
-| `commands`    | remoto | comando `/baseline-ui` (`command/baseline-ui.md`) |
+| `commands`    | remoto | comandi custom in `command/*.md` (`/baseline-ui`, `/omniroute-restart`, `/review`, ...) |
+| `mcp`         | remoto | server MCP preset (Figma Desktop, Figma Developer MCP); token in `.env` |
 | `providers`   | remoto | provider opencode in `opencode.json`; chiavi in `.env` |
 | `plugins`     | remoto | plugin npm installati nella dir config e listati in `opencode.json` |
 | `claude-mem`  | remoto | memoria: wrapper `plugins/claude-mem-plugin.js` |
@@ -52,16 +70,32 @@ oc-setup print <sezione>              stampa l'artefatto di una sezione
 ## Provider presets
 
 La sezione `providers` propone (checkbox): **GitHub Copilot**, **Google Gemini**,
-**OpenCode Zen**, **Anthropic Claude**, **OpenAI / Codex** e **OmniRoute**
-(gateway multi-modello con supporto `auto/*`). Le chiavi vengono chieste al setup
-solo per i provider che le richiedono (`GOOGLE_GENERATIVE_AI_API_KEY`,
-`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) e finiscono solo nel `.env` remoto.
-Per OmniRoute viene chiesto l'URL del gateway (default `http://127.0.0.1:20128`).
+**OpenCode Zen**, **Anthropic Claude**, **OpenAI / Codex**, **OmniRoute**
+(gateway multi-modello con supporto `auto/*`) e **Ollama / vLLM** (modelli locali
+OpenAI-compatible: viene chiesto il base URL, default `http://127.0.0.1:11434/v1`).
+Le chiavi vengono chieste al setup solo per i provider che le richiedono
+(`GOOGLE_GENERATIVE_AI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) e
+finiscono solo nel `.env` remoto. Per OmniRoute viene chiesto l'URL del gateway
+(default `http://127.0.0.1:20128`).
 
 Il modello default è scelto automaticamente (con OmniRoute: `omniroute/auto/best-coding`,
 altrimenti il primo modello del primo provider attivo), insieme a `small_model`.
 Un'opzione del setup aggiunge i tuning collaudati `tool_output` e `compaction`.
 
+## Comandi custom
+
+La sezione `commands` installa agent in `~/.config/opencode/command/*.md`:
+`/baseline-ui` (baseline interfacce), `/omniroute-restart` (riavvia il container
+Docker OmniRoute e attende che sia `healthy`), `/review`, `/refactor`, `/tests`,
+`/commit`, `/explain`.
+
+## MCP
+
+La sezione `mcp` scrive il blocco `mcp` di `opencode.json` con i preset:
+**Figma Desktop** (Dev Mode, `http://127.0.0.1:3845/mcp`, nessun segreto) e
+**Figma Developer MCP** (stdio via `npx figma-developer-mcp`; il Figma personal
+token finisce in `.env` sul server, mai in `config.json`).
+
 ## Client
 
 I client espongono i comandi `oc-*` e mostrano le **sessioni delle ultime 24 ore**

package/bin/oc-setup.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { run, cmdStatus, cmdActivate, cmdDeactivate, cmdGenerate, cmdPrint, runPrintClient } from "../src/setup.js"
 import { runUninstall } from "../src/uninstall.js"
+import { ui } from "../src/i18n.js"
 
 const argv = process.argv.slice(2)
 
-const HELP = `oc-setup — OpenCode Wyvern
+const HELP = ui(`oc-setup — OpenCode Wyvern
 
 Setup modulare per OpenCode: installi tutto, attivi quello che vuoi.
 Nessun dato privato è incluso nel pacchetto: host, utente, chiavi e
@@ -22,8 +23,35 @@ Uso:
   oc-setup --help | -h                  questo aiuto
 
 Sezioni:
-  ssh, client-pwsh, client-bash, server, commands, providers, plugins, claude-mem
-`
+  ssh, client-pwsh, client-bash, server, commands, mcp, providers, plugins, claude-mem
+
+Uscita dal wizard:
+  TUI:  Esc / Ctrl+C                  Fallback (NON terminale): rispondi 'q'
+  Lingua: rilevata dalla locale di sistema; override con OC_LANG=it o OC_LANG=en
+`, `oc-setup — OpenCode Wyvern
+
+Modular setup for OpenCode: install everything, activate what you want.
+No private data is included in the package: host, user, keys and API
+keys are requested/created locally during execution.
+
+Usage:
+  oc-setup                              starts the interactive wizard
+  oc-setup generate                     re-applies active sections from config
+  oc-setup uninstall                    complete uninstall (client, config, cache, SSH alias)
+  oc-setup status                       shows modules and status
+  oc-setup activate <section>           activates a module
+  oc-setup deactivate <section>         deactivates a module
+  oc-setup print <section>              prints the artifact of a section
+  oc-setup --version | -v               shows the version
+  oc-setup --help | -h                  this help
+
+Sections:
+  ssh, client-pwsh, client-bash, server, commands, mcp, providers, plugins, claude-mem
+
+Leaving the wizard:
+  TUI:  Esc / Ctrl+C                  Fallback (NON terminal): answer 'q'
+  Language: detected from system locale; override with OC_LANG=it or OC_LANG=en
+`)
 
 if (argv.includes("--help") || argv.includes("-h")) {
   console.log(HELP)
@@ -39,7 +67,7 @@ const printIdx = argv.indexOf("--print-client")
 if (printIdx !== -1) {
   const kind = argv[printIdx + 1]
   if (kind !== "pwsh" && kind !== "bash") {
-    console.error("uso: oc-setup --print-client <pwsh|bash>")
+    console.error(ui("uso: oc-setup --print-client <pwsh|bash>", "usage: oc-setup --print-client <pwsh|bash>"))
     process.exit(2)
   }
   await runPrintClient(kind)
@@ -53,11 +81,11 @@ try {
       await cmdStatus()
       break
     case "activate":
-      if (!arg1) fail("uso: oc-setup activate <sezione>")
+      if (!arg1) fail(ui("uso: oc-setup activate <sezione>", "usage: oc-setup activate <section>"))
       await cmdActivate(arg1)
       break
     case "deactivate":
-      if (!arg1) fail("uso: oc-setup deactivate <sezione>")
+      if (!arg1) fail(ui("uso: oc-setup deactivate <sezione>", "usage: oc-setup deactivate <section>"))
       await cmdDeactivate(arg1)
       break
     case "generate":
@@ -67,14 +95,14 @@ try {
       await runUninstall()
       break
     case "print":
-      if (!arg1) fail("uso: oc-setup print <sezione>")
+      if (!arg1) fail(ui("uso: oc-setup print <sezione>", "usage: oc-setup print <section>"))
       await cmdPrint(arg1)
       break
     case undefined:
       await run(argv)
       break
     default:
-      fail(`comando sconosciuto: ${sub}`)
+      fail(ui("comando sconosciuto:", "unknown command:") + ` ${sub}`)
   }
 } catch (err) {
   console.error(`\n[error] ${err && err.message ? err.message : err}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-wyvern",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Setup modulare per OpenCode: SSH, client PowerShell/bash (comandi oc-*), configurazione server opencode, provider, plugin e comandi custom. Installi tutto, attivi quello che vuoi.",
   "type": "module",
   "license": "MIT",
@@ -9,7 +9,7 @@
     "url": "https://github.com/Rhaegal222"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.12.0"
   },
   "bin": {
     "oc-setup": "bin/oc-setup.js"
@@ -36,6 +36,10 @@
     "url": "git+https://github.com/Rhaegal222/opencode-wyvern.git"
   },
   "scripts": {
-    "test": "node bin/oc-setup.js --help"
+    "test": "node bin/oc-setup.js --help",
+    "prepack": "node scripts/check-secrets.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.0"
   }
-}
+}

package/src/client.js

@@ -1,8 +1,10 @@
 import fs from "node:fs"
+import path from "node:path"
 import crypto from "node:crypto"
-import { render, readTemplate } from "./config.js"
+import { render, readTemplate, ensureDir } from "./config.js"
 import { pwshProfilePath, bashRcPath } from "./shell.js"
 import { c } from "./prompts.js"
+import { ui } from "./i18n.js"
 
 export const MARKER = "# ---- OpenCode Wyvern (auto-generato) ----"
 /** Marker storici: un blocco generato in passato va comunque rimosso. */
@@ -31,6 +33,7 @@ export function renderClient(kind, { server, host, user, dir }) {
 
 /** Sostituisce/crea il blocco generato in un profilo, con backup. */
 function upsertBlock(filePath, block, { dryRun = false } = {}) {
+  ensureDir(path.dirname(filePath)) // la dir del profilo può non esistere (machina nuova)
   const existed = fs.existsSync(filePath)
   let content = existed ? fs.readFileSync(filePath, "utf8") : ""
 
@@ -100,10 +103,11 @@ export async function installClient(cfg, { targets = ["pwsh", "bash"], onlyPrint
     results.push(upsertBlock(target.path(), block))
   }
 
-  console.log(c.green("\nClient installato:"))
+  console.log(c.green(`${ui("\nClient installato:", "\nClient installed:")}`))
   for (const r of results) {
     console.log(`  - ${r.filePath}${r.backup ? `  (backup: ${r.backup})` : ""}`)
   }
-  console.log(c.dim("\nRicarica il profilo con:  . $PROFILE   (PowerShell)  /  source ~/.bashrc   (bash)"))
+  console.log(c.dim(ui("\nRicarica il profilo con:  . $PROFILE   (PowerShell)  /  source ~/.bashrc   (bash)",
+    "\nReload your profile with:  . $PROFILE   (PowerShell)  /  source ~/.bashrc   (bash)")))
   return { installed: results }
 }

package/src/i18n.js

@@ -0,0 +1,19 @@
+/**
+ * Localizzazione interfacce.
+ *
+ * Rileva la locale di sistema e rende coerente TUTTA la GUI:
+ * - locale che inizia con "it" → italiano
+ * - altrimenti → inglese
+ *
+ * Override: `OC_LANG=it` oppure `OC_LANG=en`.
+ */
+const raw = process.env.OC_LANG || process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || ""
+const sys = raw || (Intl?.DateTimeFormat?.().resolvedOptions?.().locale ?? "") || "en"
+
+export const LANG = /^it\b/i.test(sys) ? "it" : "en"
+export const isIt = LANG === "it"
+export const ui = (it, en) => (isIt ? it : en)
+
+export const qHint   = ui("q=esci", "q=quit")
+export const qLegend = ui("q=Esci", "q=Exit")
+export const cancelMsg = ui("annullato.", "cancelled.")

package/src/prompts.js

@@ -1,4 +1,5 @@
-import { stdin as input, stdout as output } from "node:process"
+import { stdin as input, stdout as output, stderr as stderrStream } from "node:process"
+import { ui, isIt, qHint, qLegend, cancelMsg } from "./i18n.js"
 
 const color = (code, s) => `\x1b[${code}m${s}\x1b[0m`
 export const c = {
@@ -10,6 +11,131 @@ export const c = {
   bold: (s) => color(1, s),
 }
 
+// --------------------------------------------------------------------------
+// Backend TUI nativo Node (@clack/prompts) — cross-platform.
+// Quando stdin/stdout/stderr sono un terminale reale, i prompt diventano
+// dialoghi interattivi identici su Windows/pwsh, WSL, Linux e macOS
+// (frecce, Spazio, invio, Esc/Ctrl+C per annullare, exit code 0).
+// Negli altri casi (pipe, CI, non-interattivo) si usa il fallback a righe.
+// `secret` mantiene l'input mascherato (via clack password o raw mode).
+//
+// Il modulo @clack/prompts è importato dinamicamente: se manca (repo senza
+// `npm install`) si cade automaticamente sul fallback a righe.
+// --------------------------------------------------------------------------
+
+let cpModule = null
+let cpTried = false
+
+async function clack() {
+  if (!cpTried) {
+    cpTried = true
+    try {
+      cpModule = await import("@clack/prompts")
+    } catch {
+      cpModule = null // dipendenza non installata: fallback a righe
+    }
+  }
+  return cpModule
+}
+
+const realTty = () => !!input.isTTY && !!output.isTTY && !!stderrStream.isTTY
+
+// --------------------------------------------------------------------------
+// Footer (@clack/prompts): localizziamo gli array di istruzioni esportati
+// (MULTISELECT_INSTRUCTIONS/SELECT_INSTRUCTIONS) PRIMA che il prompt li usi.
+// Non intercettiamo mai output.write: clack salva il frame reso per calcolare
+// cursore/cancellazione, quindi un contenuto modificato dopo lo write lo
+// desincronizza (le righe si duplicano senza refresh).
+// --------------------------------------------------------------------------
+function applyInstructions(cp) {
+  const dim = (s) => `\x1b[2m${s}\x1b[0m`
+  const multi = [
+    `${dim("\u2191/\u2193")} ${ui("per navigare", "to navigate")}`,
+    `${dim(ui("Spazio:", "Space:"))} ${ui("seleziona", "select")}`,
+    `${dim(ui("Invio:", "Enter:"))} ${ui("conferma", "confirm")}`,
+    `${dim("q:")} ${qLegend}`,
+  ]
+  const sel = [
+    `${dim("\u2191/\u2193")} ${ui("per navigare", "to navigate")}`,
+    `${dim(ui("Invio:", "Enter:"))} ${ui("conferma", "confirm")}`,
+    `${dim("q:")} ${qLegend}`,
+  ]
+  if (Array.isArray(cp.MULTISELECT_INSTRUCTIONS)) cp.MULTISELECT_INSTRUCTIONS.splice(0, cp.MULTISELECT_INSTRUCTIONS.length, ...multi)
+  if (Array.isArray(cp.SELECT_INSTRUCTIONS)) cp.SELECT_INSTRUCTIONS.splice(0, cp.SELECT_INSTRUCTIONS.length, ...sel)
+}
+
+async function tuiOn() {
+  const cp = await clack()
+  const ok = !!(cp && realTty())
+  if (ok) applyInstructions(cp)
+  return ok
+}
+
+// --------------------------------------------------------------------------
+// Uscita con "q" anche in TUI: @clack/prompts supporta `signal` (abort → il
+// prompt si risolve in CANCEL_SYMBOL). Ascoltiamo il keypress 'q' su stdin e
+// abortiamo il segnale condiviso; Esc/Ctrl+C restano gestiti da clack.
+// NB: un incolla (CTRL+SHIFT+V) arriva come raffica di keypress: se il testo
+// contiene una 'q' non deve chiudere il wizard. Riconosciamo la raffica dalla
+// frequenza dei caratteri e mettiamo una tolleranza per la prima lettera.
+// --------------------------------------------------------------------------
+const quitKey = new AbortController()
+let quitArmed = false
+let lastKeyTs = 0
+let burstLen = 0
+let quitTimer = null
+
+function cancelQuit() {
+  if (quitTimer) {
+    clearTimeout(quitTimer)
+    quitTimer = null
+  }
+}
+
+function armQuitKey() {
+  if (quitArmed) return
+  quitArmed = true
+  try {
+    input.on("keypress", (str) => {
+      const now = Date.now()
+      burstLen = now - lastKeyTs > 400 ? 1 : burstLen + 1
+      lastKeyTs = now
+
+      // qualunque altro carattere cancella un'eventuale 'q' in sospeso
+      if (str !== "q" && str !== "Q") {
+        cancelQuit()
+        return
+      }
+      // 'q' nel mezzo di una raffica (incolla / tasto ripetuto): ignora
+      if (burstLen > 1) {
+        cancelQuit()
+        return
+      }
+      // 'q' isolata: aspetta ~200ms: se arrivano altri caratteri era un
+      // incolla e la prima lettera coincideva con la "q", altrimenti esce.
+      if (quitTimer) return
+      quitTimer = setTimeout(() => {
+        quitTimer = null
+        quitKey.abort()
+      }, 200)
+    })
+  } catch {
+    /* stdin senza keypress: resta Esc/Ctrl+C */
+  }
+}
+
+/** Opzioni clack con signal condiviso e suffisso "q=esci/q=quit" nel messaggio. */
+function clackOpts(message, opts = {}) {
+  armQuitKey()
+  return { ...opts, signal: quitKey.signal, message: `${message} ${color(90, `(${qHint})`)}` }
+}
+
+function abortSetup() {
+  closePrompts()
+  console.log(c.yellow(`\n  ${cancelMsg}`))
+  process.exit(0)
+}
+
 function enableRaw() {
   try {
     input.setRawMode(true)
@@ -48,7 +174,7 @@ function readLineFallback(done) {
 }
 
 /** Legge una riga da tastiera. `masked` oscura la digitazione (per segreti); */
-/** gestisce backspace e Ctrl+C. */
+/** gestisce backspace, Ctrl+C (annullamento pulito) e incolla (CTRL+SHIFT+V). */
 export function readLine({ masked = false, allowEmpty = false } = {}, done) {
   if (!enableRaw()) {
     readLineFallback(done)
@@ -57,6 +183,8 @@ export function readLine({ masked = false, allowEmpty = false } = {}, done) {
 
   let buf = ""
   const onData = (chunk) => {
+    // marcatori "bracketed paste" del terminale: se presenti vanno ignorati
+    chunk = chunk.replace(/\x1b\[200~|\x1b\[201~/g, "")
     for (const ch of chunk) {
       if (ch === "\r" || ch === "\n") {
         if (!allowEmpty && buf === "") continue
@@ -64,12 +192,13 @@ export function readLine({ masked = false, allowEmpty = false } = {}, done) {
         input.setRawMode(false)
         input.pause()
         output.write("\n")
-        return done(buf)
+        // Windows e alcuni editor incollano con \r\n finale: scarta il \r
+        return done(buf.replace(/\r+$/u, ""))
       }
-      if (ch === "\u0003") {
-        input.setRawMode(false)
-        input.pause()
-        process.exit(130)
+      if (ch === "\u0003" || ch === "\u0004") {
+        // Ctrl+C / Ctrl+D: annullamento pulito (uguale a clack isCancel),
+        // MAI un'uscita "muta" che lascia il terminale sporco.
+        abortSetup()
       }
       if (ch === "\u007f" || ch === "\b") {
         if (buf.length) {
@@ -85,57 +214,61 @@ export function readLine({ masked = false, allowEmpty = false } = {}, done) {
   input.on("data", onData)
 }
 
-/** Domanda a testo semplice con default opzionale. */
-export async function ask(question, { defaultValue = "", hint = "", validate } = {}) {
+// --------------------------------------------------------------------------
+// Implementazioni classiche (fallback a righe, stesse API precedenti).
+// --------------------------------------------------------------------------
+
+async function askClassic(question, { defaultValue = "", hint = "", validate } = {}) {
   const suffix = hint ? ` ${c.dim(`(${hint})`)}` : ""
   const def = defaultValue ? c.dim(`[${defaultValue}]`) : ""
+  const err = ui("risposta non valida, riprova.", "invalid answer, try again.")
   // eslint-disable-next-line no-constant-condition
   for (;;) {
-    output.write(`${c.cyan("?")} ${question}${suffix} ${def}\n> `)
+    output.write(`${c.cyan("?")} ${question}${suffix} ${def} ${c.dim(`(${qHint})`)}\n> `)
     const raw = await new Promise((resolve) => readLine({}, resolve))
+    if (/^q$/i.test(raw.trim())) abortSetup()
     const value = raw.trim() === "" ? defaultValue : raw.trim()
     if (validate && !validate(value)) {
-      console.log(c.yellow("  risposta non valida, riprova."))
+      console.log(c.yellow(`  ${err}`))
       continue
     }
     return value
   }
 }
 
-/** Domanda sì/no con default indicato in maiuscolo. */
-export async function confirm(question, defaultValue = false) {
-  const hint = defaultValue ? "S/n" : "s/N"
+async function confirmClassic(question, defaultValue = false) {
+  const hint = defaultValue ? ui("S/n", "Y/n") : ui("s/N", "y/N")
+  const err = ui("rispondi s o n.", "answer y or n.")
   // eslint-disable-next-line no-constant-condition
   for (;;) {
-    output.write(`${c.cyan("?")} ${question} ${c.dim(`(${hint})`)}\n> `)
+    output.write(`${c.cyan("?")} ${question} ${c.dim(`(${hint}, ${qHint})`)}\n> `)
     const a = (await new Promise((resolve) => readLine({}, resolve))).trim().toLowerCase()
+    if (a === "q") abortSetup()
     if (a === "") return defaultValue
     if (/^(s|si|sì|y|yes)$/.test(a)) return true
     if (/^(n|no)$/.test(a)) return false
-    console.log(c.yellow("  rispondi s o n."))
+    console.log(c.yellow(`  ${err}`))
   }
 }
 
-/** Selezione singola (indice numerico). */
-export async function select(question, choices, { defaultValue = 0 } = {}) {
+async function selectClassic(question, choices, { defaultValue = 0 } = {}) {
   console.log(`\n${c.cyan("?")} ${question}`)
   choices.forEach((choice, i) => {
     console.log(`  ${i + 1}. ${choice.label}`)
   })
-  return choices[Number(await ask("Scelta (numero)", {
+  return choices[Number(await askClassic(ui("Scelta (numero)", "Choice (number)"), {
     defaultValue: String(defaultValue + 1),
     validate: (v) => /^\d+$/.test(v) && Number(v) >= 1 && Number(v) <= choices.length,
   })) - 1]
 }
 
-/** Selezione multipla: numeri separati da virgola/spazio (es. "1,3,5"); invio = nessuna. */
-export async function checkbox(question, choices, { defaultIndices = [] } = {}) {
-  console.log(`\n${c.cyan("?")} ${question} ${c.dim("(invio = nessuno; es. 1,3,5)")}`)
+async function checkboxClassic(question, choices, { defaultIndices = [] } = {}) {
+  console.log(`\n${c.cyan("?")} ${question} ${c.dim(ui("(invio = nessuno; es. 1,3,5)", "(blank = none; e.g. 1,3,5)"))}`)
   choices.forEach((choice, i) => {
     const sel = defaultIndices.includes(i) ? "•" : " "
     console.log(`  ${sel} ${i + 1}. ${choice.label}`)
   })
-  const answer = await ask("Seleziona (es. 1,3,5)", {
+  const answer = await askClassic(ui("Seleziona (es. 1,3,5)", "Select (e.g. 1,3,5)"), {
     validate: (v) => {
       const nums = v.split(/[\s,]+/).filter(Boolean)
       if (!nums.length) return true // invio = nessuno (salta)
@@ -147,10 +280,89 @@ export async function checkbox(question, choices, { defaultIndices = [] } = {})
   return [...new Set(nums.map((n) => Number(n) - 1))].map((i) => choices[i])
 }
 
+async function secretClassic(question, { allowEmpty = false } = {}) {
+  output.write(`${c.cyan("?")} ${question} ${c.dim(`(${qHint})`)}\n> `)
+  return new Promise((resolve) => readLine({ masked: true, allowEmpty }, (v) => {
+    if (/^q$/i.test(v.trim())) abortSetup()
+    resolve(v)
+  }))
+}
+
+// --------------------------------------------------------------------------
+// API pubbliche: TUI @clack/prompts (TTY) con fallback classico.
+// --------------------------------------------------------------------------
+
+/** Domanda a testo semplice con default opzionale (clack text). */
+export async function ask(question, { defaultValue = "", hint = "", validate } = {}) {
+  if (!(await tuiOn())) return askClassic(question, { defaultValue, hint, validate })
+  const cp = await clack()
+  const message = hint ? `${question} (${hint})` : question
+  const errMsg = ui("risposta non valida, riprova.", "invalid answer, try again.")
+  // eslint-disable-next-line no-constant-condition
+  for (;;) {
+    const raw = await cp.text(clackOpts(message, {
+      initialValue: defaultValue || undefined,
+      validate: (val) => {
+        const value = String(val ?? "").trim() === "" ? defaultValue : String(val).trim()
+        return validate && !validate(value) ? errMsg : undefined
+      },
+    }))
+    if (cp.isCancel(raw)) abortSetup()
+    const value = String(raw ?? "").trim() === "" ? defaultValue : String(raw).trim()
+    if (validate && !validate(value)) {
+      cp.log.error(errMsg)
+      continue
+    }
+    return value
+  }
+}
+
+/** Domanda sì/no (clack confirm). */
+export async function confirm(question, defaultValue = false) {
+  if (!(await tuiOn())) return confirmClassic(question, defaultValue)
+  const cp = await clack()
+  const v = await cp.confirm(clackOpts(question, {
+    initialValue: !!defaultValue,
+    active: isIt ? "sì" : "Yes",
+    inactive: isIt ? "no" : "No",
+  }))
+  if (cp.isCancel(v)) abortSetup()
+  return v === true
+}
+
+/** Selezione singola (clack select, frecce). */
+export async function select(question, choices, { defaultValue = 0 } = {}) {
+  if (!(await tuiOn())) return selectClassic(question, choices, { defaultValue })
+  const cp = await clack()
+  const idx = await cp.select(clackOpts(question, {
+    options: choices.map((ch, i) => ({ value: i, label: ch.label })),
+    initialValue: defaultValue ?? 0,
+  }))
+  if (cp.isCancel(idx)) abortSetup()
+  return choices[idx]
+}
+
+/** Selezione multipla (clack multiselect, frecce + Spazio). */
+export async function checkbox(question, choices, { defaultIndices = [] } = {}) {
+  if (!(await tuiOn())) return checkboxClassic(question, choices, { defaultIndices })
+  const cp = await clack()
+  const options = choices.map((ch) => ({ value: ch.value, label: ch.label }))
+  const initialValues = defaultIndices.map((i) => choices[i]?.value).filter((v) => v !== undefined)
+  const vals = await cp.multiselect(clackOpts(question, { options, initialValues, required: false }))
+  if (cp.isCancel(vals)) abortSetup()
+  const sel = new Set(vals)
+  return choices.filter((ch) => sel.has(ch.value))
+}
+
 /** Input mascherato per segreti (API key ecc.). */
 export async function secret(question, { allowEmpty = false } = {}) {
-  output.write(`${c.cyan("?")} ${question}\n> `)
-  return new Promise((resolve) => readLine({ masked: true, allowEmpty }, (v) => resolve(v)))
+  if (!(await tuiOn())) return secretClassic(question, { allowEmpty })
+  const cp = await clack()
+  const v = await cp.password(clackOpts(question, {
+    validate: allowEmpty ? () => undefined : undefined,
+  }))
+  if (cp.isCancel(v)) abortSetup()
+  return String(v ?? "")
 }
 
 export function closePrompts() {
@@ -161,4 +373,4 @@ export function closePrompts() {
     /* ok */
   }
   input.pause()
-}
+}