# Sviluppo locale git-free — Ambiente Light (dev-light)

> Guida per chi vuole sviluppare un progetto OASI **in locale**, senza git, con anteprima governata.
> Il developer NON tocca mai git: la piattaforma tiene git come storico. *"Il potere è locale, l'autorità è remota."*

## Cos'è

Modifichi i file del progetto sul TUO PC → li vedi in **anteprima** sul sito (solo per te) → quando è pronto, un **publish governato** li rende live. Niente clone git, niente branch, niente push: scarichi una **base firmata** del progetto e mandi solo il **delta** (i file che tocchi) come *overlay*.

```
  base firmata (remota)  ──scarichi──▶  cartella locale  ──editi──▶  overlay push  ──▶  anteprima
                                                                                    (publish = passo separato, gated)
```

## Prerequisiti

- **Node.js** installato (nel PATH).
- Essere **membro del progetto** (login email→PIN su `https://<progetto>.oasi.io/auth/login?surface=studio`).
- Una **base pubblicata** per il progetto (la fa il team piattaforma: `pnpm tsx scripts/publish-canonical-base.ts --project=<slug>`).

## Setup — due modi

### A) Estensione VS Code (consigliato)

1. Installa l'estensione (PowerShell):
   ```powershell
   $v="$env:TEMP\oasi-owner-loop.vsix"; irm https://dev.oasi.io/oasi-owner-loop.vsix -OutFile $v; code --install-extension $v
   ```
   Poi **ricarica VS Code** (Ctrl+Shift+P → *Developer: Reload Window*).
2. Attiva il transport git-free — Ctrl+Shift+P → *Preferences: Open User Settings (JSON)*:
   ```json
   "oasi.ownerLoop.transport.<slug>": "overlay",
   "oasi.ownerLoop.developerId": "<tuo-id>"
   ```
   (`<slug>` = lo slug del progetto, es. `termotecnica`; `<tuo-id>` = es. `nome-cognome`.)
3. Avvia — Ctrl+Shift+P → **OASI Owner Loop: Avvia live-preview** (o il tasto ▷ nel pannello *OASI Owner Loop*).
   - Crea e **apre una cartella di lavoro dedicata** `~/.oasi/dev-light/<slug>/workspace` — **modifichi lì** (non il vecchio clone git).
   - Nel canale di output *OASI Owner Loop* compare un **URL di autorizzazione**: aprilo nel browser (loggato) — **una volta sola** (poi il token è in cache).
   - Scarica la base e si mette in **watch**: ad ogni salvataggio manda l'overlay → anteprima.

### B) Client da terminale (senza VS Code)

Certificazione + primo avvio (PowerShell):
```powershell
irm https://dev.oasi.io/setup-dev-light.ps1 | iex   # oppure il client diretto:
```
Watch continuo (edit → anteprima ad ogni salvataggio):
```powershell
node $HOME\.oasi\dev-light\oasi-overlay-preview.mjs --slug=<slug> --dev=<tuo-id> --repo=$HOME\.oasi\dev-light\<slug>\workspace
```
Il client scarica la base (git-free), chiede il login una-tantum, e resta in watch.

## Il flusso quotidiano

1. **Modifica** un file dello screen o un fragment nella cartella di lavoro (`~/.oasi/dev-light/<slug>/workspace`).
2. Al salvataggio parte l'**overlay push** → vedrai `pushed overlay … @ <draft>`.
3. Il worker ricompone **base + il tuo overlay** in un **draft** governato.

## Vedere l'anteprima

- **Da VS Code**: *OASI Owner Loop: Apri la mia preview*.
- **Manuale** (loggato): apri
  `https://<slug>.oasi.io/api/preview/<slug>/mint?channel=<slug>/<tuo-id>/live`
  → imposta il cookie di preview e reindirizza al sito con la **tua** sandbox. Naviga alla schermata che hai modificato.

L'anteprima è **solo per te** (cookie firmato); il sito live resta invariato per gli altri.

**Vale su tutte le surface — in una sola tab.** Il mint imposta **un solo** cookie di anteprima per il progetto (`path:/`, valido su ogni surface: `/`, `/admin/…`, `/portal/…`): **non** va montato surface per surface. Montato una volta, **naviga normalmente nella stessa tab** e ogni pagina che hai il diritto di vedere mostra il tuo draft.

- Sei in anteprima quando vedi la **cornice ambra "Anteprima sandbox"**. (Il banner "Aggiorna ora" è un aggiornamento dell'app, **non** l'anteprima.)
- Se una pagina ti risulta **live** (senza cornice ambra), quella tab **non è in anteprima** — l'hai aperta in una tab/login diversi o è **scaduta** → **ri-monta**.
- Le aree riservate come `/admin` le vedi in anteprima solo se hai il **ruolo** per quella surface. Le pagine di **piattaforma** dentro /admin (Branding, Template Email…) restano sempre live.

## Pubblicare (rendere live) — passo GOVERNATO e separato

L'anteprima è **non-promotable**: pubblicare è un passo distinto, con approvazione umana. Il draft viene ricostruito in modo deterministico, firmato (ricevuta KMS), riconciliato nel git canonico dalla piattaforma e deployato automaticamente. Tu non tocchi git; la piattaforma registra lo storico (ogni publish è un commit tracciato, reversibile con un publish successivo).

**Su termotecnica è attivo, self-service.** Quando un draft è pronto:

1. Apri **le tue anteprime**: `https://<slug>.oasi.io/p/<slug>/dev-light`
   (basta essere membro del progetto — è la superficie giusta per te).
2. Trova il tuo draft (l'id è quello mostrato dal client dopo `pushed overlay → draft <id>`).
3. **Richiedi adozione**. Da lì in poi è il **titolare** a mandarla online: la piattaforma
   ricostruisce, firma, riconcilia e deploya.

> ⚠️ **NON** `/studio/preview-publish`: quello è il banco del titolare, dietro il gate
> operatore di piattaforma (`requireStudioAccess`). Chi sviluppa in dev-light lo trova
> chiuso — è l'errore che ha fatto perdere una giornata a uno sviluppatore, convinto che
> la pubblicazione self-service non fosse attiva.

## Risoluzione problemi

- **`fetch failed` durante il download della base** → transitorio di rete; il client/script **riprende** da solo (il download è idempotente, salta i file già presi). Rilancia se serve.
- **Blocco a `>>` in PowerShell** → NON incollare script multi-riga nella console (li corrompe). Usa il one-liner `irm … | iex` o salva su file col Blocco note.
- **Login/mint 401** → devi essere loggato con la sessione *piattaforma*: `https://<slug>.oasi.io/auth/login?surface=studio` (email→PIN), non il login del progetto.
- **Non vedo la modifica** → assicurati di aver modificato uno **screen/fragment reale** (non un file di test) e di aver aperto l'anteprima sul canale `<slug>/<tuo-id>/live`.
- **La pagina è live (niente cornice ambra), es. `/admin`** → quella tab non è in anteprima: il cookie è per-browser e `path:/` (vale su tutte le surface), quindi se è live l'anteprima è **scaduta** o l'hai aperta in una **tab/login diversi** → **ri-monta** e resta nella stessa tab. Per `/admin` serve anche il **ruolo** admin.
- **Log**: `~/.oasi/dev-light/cert.log` — mandalo al team se qualcosa non torna.

---

*Architettura completa: `docs/plans/OWNER-OPERATOR-DEV-LIGHT-ARCHITECTURE-2026-07-05.md`. Il flusso git legacy (clone + push) è sostituito da questo per lo sviluppo owner-operator.*