feat(cli): prepare and validate workspace documents offline

Reuse the runtime catalog and workspace parsers in a standalone helper paired with tht. Add document templates, safe diagnostics, local Evidence checks, native bundle builds, shared CLI fixtures and IT/EN preparation guides. Record the approved document-first specification and ticket breakdown. Refs #43.
2026-09-28 15:35:25 +02:00
parent 67ee52624c
commit 64e6b9664a
20 changed files with 2195 additions and 4 deletions
@@ -7,6 +7,64 @@ naturale, interroga in sola lettura un database aziendale e accompagna l’utent
 della SQL risultante. Il core, il catalogo PostgreSQL, Qdrant, il servizio di embedding e Pi vengono
 eseguiti in Docker; sul computer non servono Node.js, Python o Pi.

+## Preparazione e verifica dei workspace prima dello stack
+
+I primi due passi del nuovo percorso funzionano senza Docker, Node, Python, Pi o
+un file di installazione. Usare il bundle della propria piattaforma con **entrambi**
+gli eseguibili `tht` e `tht-workspace-documents` nella stessa cartella (`.exe` su
+Windows). Aggiungere la cartella al `PATH`, oppure usare il percorso completo.
+Il vecchio pacchetto con il solo `tht` non contiene questa capacità. Il bundle è
+attualmente producibile dal manutentore; pubblicazione degli asset e immagini
+Docker Hub appartengono a una fase successiva. Il resto della guida descrive ancora
+il percorso di installazione esistente.
+
+1. Scegliere una cartella nuova, esterna all'applicazione, con padre già esistente:
+
+   ```sh
+   tht workspace prepare --directory ./miei-workspace --id pratica --name "Pratica" --language it
+   ```
+
+   Sono creati `thoth-workspaces.yaml`, `pratica/workspace.yaml` e
+   `workspace-docs/pratica/README.md`. Una destinazione esistente, anche vuota, viene
+   rifiutata. Nessun servizio viene avviato; Git non viene inizializzato, nessun remoto
+   viene contattato. I database di esempio restano un sottoprogetto differito. Per
+   un repository fornito dal curatore, usare una copia locale separata e passare al
+   punto 3: è sufficiente accesso in lettura all'origine.
+2. Modificare con calma catalogo (schema v1) e descrittore workspace (schema v4).
+   Mantenere uguali `id`, `name` e l'eventuale `description` nei due file; l'id deve
+   coincidere con la cartella. Ogni cartella alla radice deve corrispondere a un
+   workspace elencato, salvo `workspace-docs` e la directory locale `.git`.
+   Connessioni, schema e credenziali dei database appartengono al Metadata Catalog
+   dell'installazione. Le Evidence sono facoltative e inizialmente assenti.
+3. Verificare, correggere il documento/campo indicato e ripetere:
+
+   ```sh
+   tht workspace validate --directory ./miei-workspace
+   tht workspace validate --directory ./miei-workspace --json
+   ```
+
+   Su PowerShell usare gli stessi argomenti, ad esempio
+   `C:\ThothII\bin\tht.exe workspace validate --directory C:\ThothII\miei-workspace`.
+   Il controllo non modifica file. Rifiuta YAML multipli o malformati, chiavi/id
+   duplicati, campi sconosciuti, incoerenze tra catalogo, cartelle e descrittori,
+   riferimenti locali mancanti e link simbolici. Correggere il primo errore del
+   documento e ripetere per vedere eventuali errori successivi.
+
+Evidence `absent` è valido. Per filesystem si verificano directory, accessibilità e
+riferimenti letterali; per le selezioni Markdown standard anche i limiti dichiarati.
+Evidence v2 richiede `curated/` e frontmatter con sintassi YAML valida. I limiti locali
+sono 1 MiB per documento letto e 100.000 elementi per albero Evidence. Pattern
+arbitrari, contratto completo delle unità curate, provenienza, accesso HTTP/S3 e
+indicizzazione restano controlli runtime espliciti. Vedere la [guida Evidence](../evidence.md).
+
+Il JSON espone `schema_version`, `scope: local-documents`, `ok`, `workspaces`, `issues`
+e `deferred_checks`. I problemi riportano documento, campo, codice, correzione e,
+quando disponibile, riga YAML, senza stampare i valori del documento. Exit status:
+`0` successo locale, `1` documenti/accesso/bundle da correggere, `2` argomenti errati.
+Il successo locale non certifica verità semantica, connettività o readiness. La
+revisione Git attivata in seguito deve contenere i documenti verificati; il comando
+non pubblica file non committati o directory vuote.
+
 ## Prima di iniziare: i due repository

 Servono due repository distinti: