Metadata-Version: 2.4
Name: sintropi-bootstrap
Version: 2605.12.1016
Summary: Bootstrap and launcher for the sintropi-code CLI — authenticates via Keycloak PKCE and pulls the right engine version from each Sintropi gateway.
Project-URL: Homepage, https://bitbucket.org/eight-twenty/sintropi-bootstrap
Author-email: Eight20 <dev@eight-twenty.com>
License: Proprietary
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: requests>=2.28
Description-Content-Type: text/markdown

# sintropi-bootstrap

Bootstrap pubblico per la CLI `sintropi-code` — l'engine multi-agent di **Sintropi**.

Permette a uno sviluppatore di installare, autenticare e mantenere allineata la versione di `sintropi-code` corretta per ogni ambiente Sintropi (dev, qa, prod, tenant cliente).

## Installazione

```bash
pip install sintropi-bootstrap
```

## Uso

```bash
# Primo setup o switch ambiente (idempotente)
sintropi-bootstrap https://gateway.acme.eight20.com

# Comando principale — auto-detect versione, auto-download se cambiata
sintropi-code generate "App per la gestione ordini"
sintropi-code bootstrap my-app -o ./output/my-app
```

## Come funziona

1. `sintropi-bootstrap <gateway>`
   - Legge `GET {gateway}/api/bootstrap/config` (pubblico) → `{ keycloak_url, realm, client_id, current_sha, current_version }`
   - Avvia Authorization Code + PKCE su loopback `http://localhost:PORT` (RFC 8252) — apre il browser sulla pagina Keycloak standard
   - Verifica che l'utente abbia il ruolo realm `sintropi-code`
   - Scarica il wheel via `GET {gateway}/api/bootstrap/download` (Bearer JWT)
   - Crea un venv isolato in `~/.sintropi/versions/{sha}/.venv/` e ci installa `sintropi-agents`
   - Registra il gateway in `~/.sintropi/config.json`

2. `sintropi-code [args]`
   - Legge il gateway corrente da `~/.sintropi/config.json`
   - Verifica (con cache TTL 5 min) il SHA dell'engine corrente del gateway
   - Se diverso o assente → re-auth + download + install (transparente)
   - `exec` in `~/.sintropi/versions/{sha}/.venv/bin/python -m sintropi_agents.main <args>`

## Layout filesystem

```
~/.sintropi/
├── credentials.json    # token per-gateway (chmod 600)
├── config.json         # gateway noti + current + ultimo check
└── versions/
    ├── {sha-abc123}/
    │   ├── .venv/      # venv isolato con sintropi-agents installato
    │   └── manifest.json
    └── {sha-def456}/
        ├── .venv/
        └── manifest.json
```

Ogni gateway può avere una versione diversa dell'engine. La cache locale supporta più ambienti simultaneamente: switchare è istantaneo se la versione è già scaricata.

## Switch ambiente

`sintropi-bootstrap` è **idempotente**. Rilanciarlo con un URL diverso fa lo switch:

```bash
sintropi-bootstrap https://gateway.dev.acme.eight20.com    # ambiente dev
sintropi-code generate "..."

sintropi-bootstrap https://gateway.prod.acme.eight20.com   # switch a prod
sintropi-code generate "..."   # ora usa l'engine di prod
```

In alternativa, override puntuale con flag:

```bash
sintropi-code --gateway https://gateway.qa.acme.eight20.com generate "..."
```

## Permesso negato (ruolo mancante)

Per scaricare l'engine serve il ruolo realm Keycloak `sintropi-code`. Se sei loggato ma il ruolo non è assegnato, `sintropi-bootstrap` (e `sintropi-code`) stampano un riquadro con le istruzioni:

```
────────────────────────────────────────────────────────────────────────
 Permesso negato: ruolo mancante
────────────────────────────────────────────────────────────────────────

 Utente:        mario.rossi@eight-twenty.com
 Realm:         acme
 Ruolo serve:   sintropi-code

 Come richiedere l'accesso:

 1. Contatta l'amministratore Keycloak del realm 'acme' e chiedi
    di assegnarti il ruolo realm 'sintropi-code'.

 2. L'admin può farlo dalla console Keycloak:
    https://auth.acme.eight20.com/admin/acme/console/
    → Users → mario.rossi@eight-twenty.com → Role mapping → Assign role → sintropi-code

 3. Una volta assegnato il ruolo, rilancia lo stesso comando:
    il token verrà rinnovato automaticamente e il download partirà.
```

L'errore esce con exit code `2`.

## Uso da Claude Cowork (Claude Desktop)

> **TL;DR** — Claude Cowork in modalità Desktop standard esegue le operazioni direttamente sul computer locale dell'utente. In questo scenario `sintropi-bootstrap` usa un normale flow OAuth2 PKCE locale e **non richiede alcun tunnel SSH**.

### Caso standard (Cowork locale)

Tutto avviene sullo stesso PC dell'utente:

- Terminale locale aperto da Cowork
- Browser di default locale per la pagina di login Keycloak
- Loopback `http://localhost:PORT` per il callback OAuth
- Cache `~/.sintropi/` persistente nell'home utente

L'utente può chiedere a Cowork: *"Installa sintropi-code, agganciati al gateway `https://gateway.acme.eight20.com` e genera un'app in `~/projects/contracts-app`"*. Cowork mostra il piano (`pip install` + `sintropi-bootstrap` + `sintropi-code generate`), chiede approvazione e lo esegue. Niente configurazione di rete extra.

### Caso avanzato (shell remota / cloud)

Solo se la shell in cui gira `sintropi-bootstrap` **non** è sullo stesso host del browser:

- SSH verso una VM remota / container remoto / cloud shell
- CI/CD job che vuole installare l'engine
- Claude Code in versione web-hosted (non Cowork Desktop)

In questi scenari serve esporre il loopback verso la workstation dell'utente con un tunnel SSH `-L`. L'URL Keycloak viene stampato in console: lo apri dal browser locale, completi il login, il redirect torna sul tunnel al loopback remoto.

Raccomandazioni per ambienti remoti condivisi:
- usare un account utente personale (non shared) per l'autenticazione
- non lasciare `~/.sintropi/credentials.json` su host non personali
- se possibile, preferire l'esecuzione locale (Cowork Desktop) e poi sincronizzare il risultato

## Sicurezza

- **Client public + PKCE**: nessun secret nel pacchetto né nella cache
- **Loopback**: il redirect torna su `http://localhost:PORT` random, niente esposizione di rete
- **State + PKCE verifier**: protezione CSRF e code interception
- **Role check server-side**: il gateway nega il download senza ruolo `sintropi-code`
- **SHA-256 verificato** sul wheel scaricato (oltre al TLS)

## Licenza

Proprietary — © Eight20.
