IdeA/docs/ticket13-f0-frontend-transport-inventory.md

# Ticket #13 — Lot B0/F0 : inventaire du transport frontend (TS/React)

> Livrable d'inventaire. **Aucun code de feature modifié.** Miroir frontend de
> l'inventaire backend (`ticket13-b0-backend-transport-inventory.md`).
> Objectif : cartographier tous les accès `@tauri-apps/api`, les classer par nature
> (request/response · stream · event · desktop-only), et localiser la frontière
> « gateways TS transport-neutres » du lot F1 (adapter Tauri desktop | adapter
> HTTP+WS web).

## 0. Constat majeur — la frontière F1 existe déjà (à ~90 %)

Le frontend est **déjà** structuré exactement comme le plan cible le demande :

- **Ports transport-neutres** : `src/ports/index.ts` déclare 21 gateways (interfaces
  TS) décrivant *ce dont l'UI a besoin*, sans aucune référence à Tauri. Toute la
  couche `features/` + `app/` dépend de ces ports via DI (`useGateways()`).
- **Adapters = seul lieu Tauri** : `src/adapters/*` implémente les ports via
  `@tauri-apps/api`. C'est le **seul** répertoire autorisé à importer Tauri.
- **Garde d'architecture L1 active** : `src/app/no-direct-invoke.test.ts` échoue en CI
  si un fichier hors `src/adapters` importe `@tauri-apps/api` **ou** appelle `invoke(`.
  Cette garde est notre filet de sécurité pour F1 : elle garantit qu'aucun composant
  n'appelle Tauri en dur — donc **aucun composant métier à réécrire** pour le web.
- **Composition déjà bifurquée** : `src/app/di.tsx` → `resolveGateways()` choisit
  `createTauriGateways()` vs `createMockGateways()` selon `VITE_USE_MOCK`. F1 ajoute
  simplement une **3ᵉ implémentation** (`createHttpWsGateways()`) au même seam.

**Conséquence sur le plan de lots** : F1 n'est *pas* une extraction de frontière
(elle est faite), mais l'écriture d'un **second jeu d'adapters** derrière des ports
inchangés. Le risque est concentré dans **3 adapters à flux (Channel)** et **3 usages
desktop-only**, pas dans les 15 gateways request/response (mécaniques).

## 1. Inventaire exhaustif des accès `@tauri-apps/api`

Aucun accès hors `src/adapters`. Détail par fichier adapter :

| Adapter | API Tauri utilisée | Nature | Commentaire transport |
|---|---|---|---|
| `system.ts` | `invoke` (`health`) | request/response | trivial HTTP |
| `system.ts` | `listen("domain://event")` | **event** | bus d'événements domaine global → **WS** (fan-out serveur→client) |
| `system.ts` | `open()` de `@tauri-apps/plugin-dialog` | **desktop-only** | picker dossier natif — **pas de sens sur web** (voir §4) |
| `agent.ts` | `invoke` (list/create/change/read/update/delete/…) | request/response | HTTP |
| `agent.ts` | `Channel<number[]>` (`launch_agent`, `reattach_terminal`) | **stream** | flux PTY agent → **WS** (contrat PTY du carnet) |
| `terminal.ts` | `Channel<number[]>` (`open_terminal`, `reattach_terminal`) | **stream** | flux PTY terminal → **WS** (cœur de F3) |
| `terminal.ts` | `invoke` (`write_/resize_/close_terminal`) | request/response (contrôle PTY) | messages WS client→serveur (input/resize/close) |
| `ticket.ts` | `Channel<ReplyChunk>` (`agent_send`) | **stream** | flux de réponse chat assistant ticket → **WS** |
| `ticket.ts` | `invoke` (~20 commandes `ticket_*`) | request/response | HTTP |
| `window.ts` | `invoke` (`open_/close_/list_view_window`) | **desktop-only** | cycle de vie fenêtre OS (WebviewWindow) — voir §4 |
| `window.ts` | `listen("view-window://lifecycle")` | **desktop-only / event** | fermeture fenêtre OS — voir §4 |
| `focusedProject.ts` | `invoke` + `listen("focused-project://changed")` | **desktop-only / event** | canal fenêtre principale ⇄ fenêtre détachée — voir §4 |
| `project.ts`, `layout.ts`, `git.ts`, `profile.ts`, `modelServer.ts`, `template.ts`, `skill.ts`, `memory.ts`, `embedder.ts`, `permission.ts`, `workState.ts`, `conversation.ts`, `input.ts` | `invoke` seul | request/response | HTTP mécanique |
| `uiPreferences.ts` | *(aucune)* — `localStorage` | frontend-pur | déjà transport-neutre, marche tel quel sur web |

## 2. Classement par nature de transport

### 2a. `request/response` (le gros du volume — mapping HTTP direct)
Tous les `invoke()` non-Channel. 15 gateways sur 21 sont **exclusivement**
request/response : `project, layout, git, profile, modelServer, template, skill,
memory, embedder, permission, workState, conversation, input`, + le `health` de
`system` et les ~20 commandes `ticket_*`.
→ **Aucune décision d'archi** : un adapter HTTP générique (POST `{command, args}` ou
route par commande) suffit. C'est le socle du **premier livrable B4/F2** (web ouvre un
projet + read-only), qui n'a besoin d'aucun stream.

### 2b. `stream` (Channel Tauri → WebSocket) — **le vrai chantier F1/F3**
Trois flux, tous modélisés côté port par un **callback `onData`/`onChunk`** (le port
ne connaît jamais `Channel`) :

1. **PTY terminal** — `terminal.ts` `openTerminal`/`reattach` : `Channel<number[]>`,
   octets bruts → `term.write`. **Cœur de F3 (xterm sur WS).**
2. **PTY agent** — `agent.ts` `launchAgent`/`reattach` : même `Channel<number[]>`,
   réutilise `makeTerminalHandle`. Même transport que le PTY terminal (le carnet dit
   « agents via WS PTY », lot B6).
3. **Chat assistant ticket** — `ticket.ts` `sendTicketChat` : `Channel<ReplyChunk>`,
   flux de réponse LLM structuré (`agent_send`). Stream applicatif, pas PTY.

Point de contrat clé : le **handle** (`TerminalHandle`) porte déjà `write/resize/
detach/close` **et** la sémantique detach≠close (détacher la vue sans tuer le PTY).
Cette sémantique **correspond exactement** au contrat PTY WebSocket du carnet
(`attach_terminal`/`detach`, PTY autorité serveur, scrollback borné). L'adapter WS
implémentera `makeTerminalHandle` en émettant `input/resize/detach/close` sur la socket
et en poussant `output(seq,bytes)` dans `onData`. **Le port n'a pas à changer.**

### 2c. `event` (listen Tauri → WebSocket serveur→client)
Un seul événement *portable* : `system.ts` `onDomainEvent("domain://event")` — le bus
d'événements domaine (agent launched, rate-limited, backgroundTaskChanged, issueDeleted,
progress modèle…). Sur web ⇒ **canal WS serveur→client** (ou multiplexé sur la même
socket que le PTY selon l'arbitrage HTTP+WS séparés vs WS unique, laissé à Architect).
Les deux autres `listen` (`view-window://lifecycle`, `focused-project://changed`) sont
**desktop-only** (§4), pas des events métier.

### 2d. `desktop-only` (pas de portage web direct — voir §4)
`system.pickFolder` (dialog natif), tout `window.ts` (WebviewWindow OS),
`focusedProject.ts` (coordination multi-fenêtres OS).

## 3. Frontière F1 : où placer les deux implémentations

**La frontière est déjà `src/ports/` ⇄ `src/adapters/`.** F1 = ajouter un dossier
`src/adapters/http/` (ou `webws/`) avec une implémentation par port, et un
`createHttpWsGateways()` branché dans `resolveGateways()`.

Découpage recommandé des adapters web par priorité (aligné sur les lots du carnet) :

- **F2 (premier livrable, request/response only)** : adapters HTTP pour `system.health`,
  `project`, `layout` (read), `workState`, `ticket` (read), `agent.listAgents` +
  `onDomainEvent` sur WS. Suffit pour « ouvrir un projet + état read-only ».
- **F3 (xterm sur WS)** : adapter WS pour `terminal` (+ réécriture de
  `makeTerminalHandle` en variante socket). `TerminalView.tsx` **ne change pas** : il ne
  connaît que le port et un `open/reattach` injecté.
- **B6/F(agents)** : `agent.launchAgent/reattach` sur le même transport WS PTY.
- **Chat ticket** : `ticket.sendTicketChat` sur WS applicatif.
- **desktop-only** : `window`, `focusedProject`, `pickFolder` → implémentations web
  dégradées/alternatives (§4).

**Aucun composant métier (`features/`, `app/`) n'appelle Tauri** — garanti par la garde
L1. Donc F1 ne touche **que** `src/adapters/`, `src/app/di.tsx` (3-way resolve) et
`vite`/build (cible web sans Tauri). C'est la bonne nouvelle du plan.

## 4. Points desktop-only — décisions à cadrer (Architect)

Ces trois surfaces n'ont pas d'équivalent WS trivial ; elles ne bloquent **pas** le
premier livrable (read-only) mais doivent être tranchées avant les lots concernés :

1. **`system.pickFolder`** (créer/ouvrir un projet par un dossier local). Sur le
   serveur, le « dossier » est **sur la machine serveur**, pas sur le client web. ⇒ Il
   faut un **file-picker serveur** (browse arborescence serveur via HTTP) au lieu du
   dialog natif OS. Impacte la création/ouverture de projet côté web. **À cadrer.**
2. **`window.ts` (détacher un panneau en fenêtre OS)** : concept purement desktop
   (Tauri `WebviewWindow`). Équivalent web = nouvel **onglet/`window.open`** navigateur,
   sémantique différente (pas de registre anti-doublon OS). V1 web : dégrader en
   **no-op** ou en onglet navigateur, la garde L1 permet une impl web distincte sans
   toucher les composants. **À cadrer (probablement hors-scope V1 web).**
3. **`focusedProject.ts`** : coordination fenêtre principale ⇄ fenêtres détachées. Sans
   fenêtres détachées (point 2), le canal se réduit à un état local. V1 web :
   implémentation triviale in-memory / `BroadcastChannel` si multi-onglets. **À cadrer.**

## 5. Signaux pour le plan de lots / contrat de transport

- ✅ **Rien ne remet en cause le plan.** La frontière gateways transport-neutres du
  carnet est **déjà réalisée et testée** (garde L1). F1 est un ajout d'adapters, pas un
  refactor de composants. Gain de risque majeur.
- ✅ **Le contrat PTY WebSocket du carnet colle au port existant** : `TerminalHandle`
  (write/resize/detach/close, detach≠close, scrollback au reattach) mappe 1-pour-1 sur
  `attach_terminal/input/resize/detach/close` + `attached(scrollback)/output(seq)`.
  Aucune évolution de port nécessaire pour F3.
- ⚠️ **3 flux Channel** (PTY terminal, PTY agent, chat ticket) partagent la même
  mécanique `onData`/callback — un **transport WS commun** peut les servir tous les
  trois. À confirmer avec le choix « HTTP+WS séparés vs WS multiplexé » (délégué
  Architect).
- ⚠️ **`pickFolder`** est le seul point request/response qui **change de sémantique** sur
  web (dossier serveur ≠ dossier client). À arbitrer avant le lot création/ouverture de
  projet web.
- ⚠️ **`window`/`focusedProject`** (multi-fenêtres OS) : probablement **hors V1 web** ;
  à confirmer pour ne pas gonfler le périmètre.
- ℹ️ **`uiPreferences`** (localStorage) marche déjà tel quel sur web — aucun adapter à
  écrire.
- ℹ️ **Convention DTO** : commandes snake_case, payloads camelCase, souvent enveloppés
  dans `{ request: {...} }`. L'adapter HTTP doit préserver cette enveloppe pour parler au
  même cœur backend (le miroir backend confirme ce point de contrat).